clawport-ui 0.1.0

package/lib/cron-pipelines.test.ts

@@ -0,0 +1,69 @@
+// @vitest-environment node
+import { describe, it, expect } from 'vitest'
+import { PIPELINES, getPipelinesForJob, getAllPipelineJobNames } from './cron-pipelines'
+
+describe('PIPELINES', () => {
+  it('has 3 pipeline definitions', () => {
+    expect(PIPELINES).toHaveLength(3)
+  })
+
+  it('Morning Briefing has correct edges', () => {
+    const p = PIPELINES.find(p => p.name === 'Morning Briefing')!
+    expect(p.edges).toHaveLength(1)
+    expect(p.edges[0]).toEqual({
+      from: 'vault-morning-snapshot',
+      to: 'builder-briefing',
+      artifact: 'vault-snapshot.json',
+    })
+  })
+
+  it('Pulse Daily Pipeline has 4 edges', () => {
+    const p = PIPELINES.find(p => p.name === 'Pulse Daily Pipeline')!
+    expect(p.edges).toHaveLength(4)
+  })
+})
+
+describe('getPipelinesForJob', () => {
+  it('finds pipelines for a source job', () => {
+    const result = getPipelinesForJob('vault-morning-snapshot')
+    expect(result).toHaveLength(1)
+    expect(result[0].name).toBe('Morning Briefing')
+  })
+
+  it('finds pipelines for a target job', () => {
+    const result = getPipelinesForJob('builder-briefing')
+    expect(result).toHaveLength(1)
+    expect(result[0].name).toBe('Morning Briefing')
+  })
+
+  it('finds multiple pipelines for jobs in multiple pipelines', () => {
+    const result = getPipelinesForJob('pulse-daily-hype-brief')
+    expect(result).toHaveLength(1) // only in Pulse Daily Pipeline
+    expect(result[0].name).toBe('Pulse Daily Pipeline')
+  })
+
+  it('returns empty for standalone jobs', () => {
+    const result = getPipelinesForJob('kaze-japan-flights')
+    expect(result).toHaveLength(0)
+  })
+})
+
+describe('getAllPipelineJobNames', () => {
+  it('returns all unique job names from pipelines', () => {
+    const names = getAllPipelineJobNames()
+    expect(names.has('vault-morning-snapshot')).toBe(true)
+    expect(names.has('builder-briefing')).toBe(true)
+    expect(names.has('pulse-feed-aggregator')).toBe(true)
+    expect(names.has('pulse-daily-hype-brief')).toBe(true)
+    expect(names.has('herald-linkedin-content')).toBe(true)
+    expect(names.has('pulse-lumen-bridge')).toBe(true)
+    expect(names.has('seo-data-drop-reminder')).toBe(true)
+    expect(names.has('seo-team-weekly')).toBe(true)
+  })
+
+  it('does not contain standalone jobs', () => {
+    const names = getAllPipelineJobNames()
+    expect(names.has('kaze-japan-flights')).toBe(false)
+    expect(names.has('robin-weekly-brief')).toBe(false)
+  })
+})

package/lib/cron-pipelines.ts

@@ -0,0 +1,58 @@
+/**
+ * Manually-defined pipeline map — describes implicit cron pipelines
+ * based on file I/O and scheduling dependencies.
+ */
+
+export interface PipelineEdge {
+  from: string
+  to: string
+  artifact: string
+}
+
+export interface Pipeline {
+  name: string
+  edges: PipelineEdge[]
+}
+
+export const PIPELINES: Pipeline[] = [
+  {
+    name: 'Morning Briefing',
+    edges: [
+      { from: 'vault-morning-snapshot', to: 'builder-briefing', artifact: 'vault-snapshot.json' },
+    ],
+  },
+  {
+    name: 'Pulse Daily Pipeline',
+    edges: [
+      { from: 'pulse-feed-aggregator', to: 'pulse-daily-hype-brief', artifact: 'pulse-feed-latest.txt' },
+      { from: 'pulse-launch-watcher', to: 'pulse-daily-hype-brief', artifact: 'pulse-launches-latest.txt' },
+      { from: 'pulse-daily-hype-brief', to: 'herald-linkedin-content', artifact: 'pulse-feed-latest.txt' },
+      { from: 'pulse-daily-hype-brief', to: 'pulse-lumen-bridge', artifact: 'hot-signals.json' },
+    ],
+  },
+  {
+    name: 'SEO Weekly Pipeline',
+    edges: [
+      { from: 'seo-data-drop-reminder', to: 'seo-team-weekly', artifact: 'SEO-Drops/' },
+    ],
+  },
+]
+
+/** Get all pipelines that include a specific job name. */
+export function getPipelinesForJob(name: string): Pipeline[] {
+  return PIPELINES.filter(p =>
+    p.edges.some(e => e.from === name || e.to === name)
+  )
+}
+
+/** Get the set of all job names that appear in any pipeline. */
+export function getAllPipelineJobNames(): Set<string> {
+  const names = new Set<string>()
+  for (const p of PIPELINES) {
+    for (const e of p.edges) {
+      names.add(e.from)
+      names.add(e.to)
+    }
+  }
+  return names
+}

package/lib/cron-runs.test.ts

@@ -0,0 +1,118 @@
+// @vitest-environment node
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+
+const { mockReadFileSync, mockReaddirSync, mockExistsSync } = vi.hoisted(() => ({
+  mockReadFileSync: vi.fn(),
+  mockReaddirSync: vi.fn(),
+  mockExistsSync: vi.fn(),
+}))
+
+vi.mock('fs', () => ({
+  readFileSync: mockReadFileSync,
+  readdirSync: mockReaddirSync,
+  existsSync: mockExistsSync,
+  default: { readFileSync: mockReadFileSync, readdirSync: mockReaddirSync, existsSync: mockExistsSync },
+}))
+
+import { getCronRuns } from './cron-runs'
+
+beforeEach(() => {
+  vi.clearAllMocks()
+  vi.stubEnv('WORKSPACE_PATH', '/tmp/test-workspace')
+  mockExistsSync.mockReturnValue(true)
+})
+
+describe('getCronRuns', () => {
+  it('parses JSONL lines and returns sorted newest-first', () => {
+    const lines = [
+      JSON.stringify({ ts: 1000, jobId: 'a', action: 'finished', status: 'ok', summary: 'done', durationMs: 5000, deliveryStatus: 'delivered' }),
+      JSON.stringify({ ts: 3000, jobId: 'a', action: 'finished', status: 'error', error: 'timeout', durationMs: 10000, deliveryStatus: 'unknown' }),
+      JSON.stringify({ ts: 2000, jobId: 'a', action: 'finished', status: 'ok', summary: 'ok', durationMs: 3000, deliveryStatus: 'delivered' }),
+    ].join('\n')
+
+    mockReaddirSync.mockReturnValue(['a.jsonl'])
+    mockReadFileSync.mockReturnValue(lines)
+
+    const runs = getCronRuns()
+    expect(runs).toHaveLength(3)
+    expect(runs[0].ts).toBe(3000)
+    expect(runs[0].status).toBe('error')
+    expect(runs[1].ts).toBe(2000)
+    expect(runs[2].ts).toBe(1000)
+  })
+
+  it('filters by jobId when provided', () => {
+    const lines = JSON.stringify({ ts: 1000, jobId: 'abc', action: 'finished', status: 'ok', durationMs: 100 })
+    mockReadFileSync.mockReturnValue(lines)
+
+    const runs = getCronRuns('abc')
+    expect(runs).toHaveLength(1)
+    expect(runs[0].jobId).toBe('abc')
+    // Should not call readdirSync when filtering by jobId
+    expect(mockReaddirSync).not.toHaveBeenCalled()
+  })
+
+  it('returns empty array when runs dir does not exist', () => {
+    mockExistsSync.mockReturnValue(false)
+    const runs = getCronRuns()
+    expect(runs).toEqual([])
+  })
+
+  it('skips non-finished actions', () => {
+    const lines = [
+      JSON.stringify({ ts: 1000, jobId: 'a', action: 'started', status: 'ok' }),
+      JSON.stringify({ ts: 2000, jobId: 'a', action: 'finished', status: 'ok', durationMs: 100 }),
+    ].join('\n')
+
+    mockReaddirSync.mockReturnValue(['a.jsonl'])
+    mockReadFileSync.mockReturnValue(lines)
+
+    const runs = getCronRuns()
+    expect(runs).toHaveLength(1)
+    expect(runs[0].ts).toBe(2000)
+  })
+
+  it('skips malformed JSON lines', () => {
+    const lines = [
+      'not valid json',
+      JSON.stringify({ ts: 1000, jobId: 'a', action: 'finished', status: 'ok', durationMs: 100 }),
+      '{ broken',
+    ].join('\n')
+
+    mockReaddirSync.mockReturnValue(['a.jsonl'])
+    mockReadFileSync.mockReturnValue(lines)
+
+    const runs = getCronRuns()
+    expect(runs).toHaveLength(1)
+  })
+
+  it('skips empty lines', () => {
+    const lines = '\n\n' + JSON.stringify({ ts: 1000, jobId: 'a', action: 'finished', status: 'ok', durationMs: 100 }) + '\n\n'
+    mockReaddirSync.mockReturnValue(['a.jsonl'])
+    mockReadFileSync.mockReturnValue(lines)
+
+    const runs = getCronRuns()
+    expect(runs).toHaveLength(1)
+  })
+
+  it('handles unreadable files gracefully', () => {
+    mockReaddirSync.mockReturnValue(['a.jsonl', 'b.jsonl'])
+    mockReadFileSync.mockImplementation((filePath: string) => {
+      if (filePath.includes('a.jsonl')) throw new Error('permission denied')
+      return JSON.stringify({ ts: 1000, jobId: 'b', action: 'finished', status: 'ok', durationMs: 100 })
+    })
+
+    const runs = getCronRuns()
+    expect(runs).toHaveLength(1)
+    expect(runs[0].jobId).toBe('b')
+  })
+
+  it('returns empty when jobId file does not exist', () => {
+    mockExistsSync.mockImplementation((p: string) => {
+      // Runs dir exists but specific file does not
+      return !p.endsWith('.jsonl')
+    })
+    const runs = getCronRuns('nonexistent')
+    expect(runs).toEqual([])
+  })
+})

package/lib/cron-runs.ts

@@ -0,0 +1,67 @@
+import { CronRun } from '@/lib/types'
+import { readFileSync, readdirSync, existsSync } from 'fs'
+import path from 'path'
+import { requireEnv } from '@/lib/env'
+
+/** Derive the cron runs directory from WORKSPACE_PATH (go up from workspace to .openclaw/cron/runs) */
+function getRunsDir(): string {
+  return path.resolve(requireEnv('WORKSPACE_PATH'), '..', 'cron', 'runs')
+}
+
+/**
+ * Parse a single JSONL line into a CronRun.
+ * Returns null if the line can't be parsed or is not a "finished" action.
+ */
+function parseLine(line: string): CronRun | null {
+  if (!line.trim()) return null
+  try {
+    const obj = JSON.parse(line)
+    if (obj.action && obj.action !== 'finished') return null
+    return {
+      ts: typeof obj.ts === 'number' ? obj.ts : 0,
+      jobId: String(obj.jobId || ''),
+      status: obj.status === 'ok' ? 'ok' : 'error',
+      summary: typeof obj.summary === 'string' ? obj.summary : null,
+      error: typeof obj.error === 'string' ? obj.error : null,
+      durationMs: typeof obj.durationMs === 'number' ? obj.durationMs : 0,
+      deliveryStatus: typeof obj.deliveryStatus === 'string' ? obj.deliveryStatus : null,
+    }
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Read JSONL run history files. Returns CronRun[] sorted newest-first.
+ * If jobId is provided, reads only that job's file. Otherwise reads all files.
+ */
+export function getCronRuns(jobId?: string): CronRun[] {
+  const runsDir = getRunsDir()
+  if (!existsSync(runsDir)) return []
+
+  let files: string[]
+  if (jobId) {
+    const filePath = path.join(runsDir, `${jobId}.jsonl`)
+    files = existsSync(filePath) ? [filePath] : []
+  } else {
+    files = readdirSync(runsDir)
+      .filter(f => f.endsWith('.jsonl'))
+      .map(f => path.join(runsDir, f))
+  }
+
+  const runs: CronRun[] = []
+  for (const filePath of files) {
+    try {
+      const content = readFileSync(filePath, 'utf-8')
+      for (const line of content.split('\n')) {
+        const run = parseLine(line)
+        if (run) runs.push(run)
+      }
+    } catch {
+      // Skip unreadable files
+    }
+  }
+
+  runs.sort((a, b) => b.ts - a.ts)
+  return runs
+}

package/lib/cron-utils.test.ts

@@ -0,0 +1,222 @@
+// @vitest-environment node
+import { describe, it, expect } from 'vitest'
+import { parseSchedule, describeCron, formatDuration, parseScheduleSlots } from './cron-utils'
+
+// --- parseSchedule ---
+
+describe('parseSchedule', () => {
+  it('handles a plain string', () => {
+    const result = parseSchedule('0 8 * * *')
+    expect(result).toEqual({ expression: '0 8 * * *', timezone: null })
+  })
+
+  it('handles object with expression + timezone', () => {
+    const result = parseSchedule({ expression: '0 8 * * *', timezone: 'America/Chicago' })
+    expect(result).toEqual({ expression: '0 8 * * *', timezone: 'America/Chicago' })
+  })
+
+  it('handles object with cron key', () => {
+    const result = parseSchedule({ cron: '0 10 * * 1-5' })
+    expect(result).toEqual({ expression: '0 10 * * 1-5', timezone: null })
+  })
+
+  it('handles object with value key', () => {
+    const result = parseSchedule({ value: '0 6 * * 1' })
+    expect(result).toEqual({ expression: '0 6 * * 1', timezone: null })
+  })
+
+  it('handles null', () => {
+    const result = parseSchedule(null)
+    expect(result).toEqual({ expression: '', timezone: null })
+  })
+
+  it('handles undefined', () => {
+    const result = parseSchedule(undefined)
+    expect(result).toEqual({ expression: '', timezone: null })
+  })
+
+  it('handles empty object', () => {
+    const result = parseSchedule({})
+    expect(result).toEqual({ expression: '', timezone: null })
+  })
+
+  it('ignores non-string timezone', () => {
+    const result = parseSchedule({ expression: '0 8 * * *', timezone: 123 })
+    expect(result).toEqual({ expression: '0 8 * * *', timezone: null })
+  })
+
+  it('handles actual data format: { kind: "cron", expr: "...", tz: "..." }', () => {
+    const result = parseSchedule({ kind: 'cron', expr: '0 6 * * *', tz: 'America/Chicago' })
+    expect(result).toEqual({ expression: '0 6 * * *', timezone: 'America/Chicago' })
+  })
+
+  it('handles expr without tz', () => {
+    const result = parseSchedule({ kind: 'cron', expr: '0 12 * * 1' })
+    expect(result).toEqual({ expression: '0 12 * * 1', timezone: null })
+  })
+
+  it('prefers expr over expression when both present', () => {
+    const result = parseSchedule({ expr: '0 6 * * *', expression: '0 8 * * *' })
+    expect(result).toEqual({ expression: '0 6 * * *', timezone: null })
+  })
+})
+
+// --- describeCron ---
+
+describe('describeCron', () => {
+  it('daily at 8:00 AM', () => {
+    expect(describeCron('0 8 * * *')).toBe('Daily at 8 AM')
+  })
+
+  it('daily at 3:00 PM', () => {
+    expect(describeCron('0 15 * * *')).toBe('Daily at 3 PM')
+  })
+
+  it('daily at 12:00 AM (midnight)', () => {
+    expect(describeCron('0 0 * * *')).toBe('Daily at 12 AM')
+  })
+
+  it('daily at 12:00 PM (noon)', () => {
+    expect(describeCron('0 12 * * *')).toBe('Daily at 12 PM')
+  })
+
+  it('daily with non-zero minutes', () => {
+    expect(describeCron('30 14 * * *')).toBe('Daily at 2:30 PM')
+  })
+
+  it('weekdays at 10:00 AM', () => {
+    expect(describeCron('0 10 * * 1-5')).toBe('Weekdays at 10 AM')
+  })
+
+  it('Mondays at 6:00 AM', () => {
+    expect(describeCron('0 6 * * 1')).toBe('Mondays at 6 AM')
+  })
+
+  it('Sundays at 12:00 AM', () => {
+    expect(describeCron('0 0 * * 0')).toBe('Sundays at 12 AM')
+  })
+
+  it('Fridays at 5:00 PM', () => {
+    expect(describeCron('0 17 * * 5')).toBe('Fridays at 5 PM')
+  })
+
+  it('Saturdays at 9:00 AM', () => {
+    expect(describeCron('0 9 * * 6')).toBe('Saturdays at 9 AM')
+  })
+
+  it('every 2 days at 12:00 PM', () => {
+    expect(describeCron('0 12 */2 * *')).toBe('Every 2 days at 12 PM')
+  })
+
+  it('every minute', () => {
+    expect(describeCron('* * * * *')).toBe('Every minute')
+  })
+
+  it('every hour', () => {
+    expect(describeCron('0 * * * *')).toBe('Every hour')
+  })
+
+  it('monthly on the 1st at 8:00 AM', () => {
+    expect(describeCron('0 8 1 * *')).toBe('Monthly on the 1st at 8 AM')
+  })
+
+  it('monthly on the 2nd at 9:00 AM', () => {
+    expect(describeCron('0 9 2 * *')).toBe('Monthly on the 2nd at 9 AM')
+  })
+
+  it('monthly on the 3rd at 10:00 AM', () => {
+    expect(describeCron('0 10 3 * *')).toBe('Monthly on the 3rd at 10 AM')
+  })
+
+  it('monthly on the 15th at 6:00 PM', () => {
+    expect(describeCron('0 18 15 * *')).toBe('Monthly on the 15th at 6 PM')
+  })
+
+  it('returns raw expression for unparseable input', () => {
+    expect(describeCron('*/5 */2 1,15 * 1-5')).toBe('*/5 */2 1,15 * 1-5')
+  })
+
+  it('returns raw expression for 6-field cron', () => {
+    expect(describeCron('0 0 8 * * *')).toBe('0 0 8 * * *')
+  })
+
+  it('returns empty string for empty input', () => {
+    expect(describeCron('')).toBe('')
+  })
+
+  it('returns empty string for whitespace-only input', () => {
+    expect(describeCron('   ')).toBe('')
+  })
+})
+
+// --- formatDuration ---
+
+describe('formatDuration', () => {
+  it('formats seconds only', () => {
+    expect(formatDuration(45000)).toBe('45s')
+  })
+
+  it('formats zero', () => {
+    expect(formatDuration(0)).toBe('0s')
+  })
+
+  it('formats minutes and seconds', () => {
+    expect(formatDuration(147116)).toBe('2m 27s')
+  })
+
+  it('formats exact minutes', () => {
+    expect(formatDuration(120000)).toBe('2m')
+  })
+
+  it('formats hours and minutes', () => {
+    expect(formatDuration(3660000)).toBe('1h 1m')
+  })
+
+  it('formats exact hours', () => {
+    expect(formatDuration(3600000)).toBe('1h 0m')
+  })
+
+  it('handles negative values', () => {
+    expect(formatDuration(-1)).toBe('—')
+  })
+
+  it('handles Infinity', () => {
+    expect(formatDuration(Infinity)).toBe('—')
+  })
+})
+
+// --- parseScheduleSlots ---
+
+describe('parseScheduleSlots', () => {
+  it('parses daily cron', () => {
+    const result = parseScheduleSlots('0 8 * * *')
+    expect(result).toEqual({ hour: 8, minute: 0, days: [0, 1, 2, 3, 4, 5, 6] })
+  })
+
+  it('parses weekday cron', () => {
+    const result = parseScheduleSlots('0 10 * * 1-5')
+    expect(result).toEqual({ hour: 10, minute: 0, days: [1, 2, 3, 4, 5] })
+  })
+
+  it('parses specific day cron', () => {
+    const result = parseScheduleSlots('0 12 * * 1')
+    expect(result).toEqual({ hour: 12, minute: 0, days: [1] })
+  })
+
+  it('parses comma-separated days', () => {
+    const result = parseScheduleSlots('30 9 * * 1,3,5')
+    expect(result).toEqual({ hour: 9, minute: 30, days: [1, 3, 5] })
+  })
+
+  it('returns null for empty input', () => {
+    expect(parseScheduleSlots('')).toBeNull()
+  })
+
+  it('returns null for 6-field cron', () => {
+    expect(parseScheduleSlots('0 0 8 * * *')).toBeNull()
+  })
+
+  it('returns null for wildcard hour', () => {
+    expect(parseScheduleSlots('0 * * * *')).toBeNull()
+  })
+})

package/lib/cron-utils.ts

@@ -0,0 +1,160 @@
+/**
+ * Cron schedule parsing and human-readable description utilities.
+ * No external dependencies — covers the ~10 patterns observed in production.
+ */
+
+const DAY_NAMES = ['Sundays', 'Mondays', 'Tuesdays', 'Wednesdays', 'Thursdays', 'Fridays', 'Saturdays']
+
+function formatTime(hour: number, minute: number): string {
+  const h = hour % 12 || 12
+  const ampm = hour < 12 ? 'AM' : 'PM'
+  const m = minute === 0 ? '' : `:${String(minute).padStart(2, '0')}`
+  return `${h}${m} ${ampm}`
+}
+
+function formatTimeWithMinute(hour: number, minute: number): string {
+  const h = hour % 12 || 12
+  const ampm = hour < 12 ? 'AM' : 'PM'
+  return `${h}:${String(minute).padStart(2, '0')} ${ampm}`
+}
+
+/**
+ * Extract a cron expression string and optional timezone from the raw schedule
+ * value returned by OpenClaw CLI. Handles:
+ * - string: "0 8 * * *"
+ * - object: { kind: "cron", expr: "0 8 * * *", tz: "America/Chicago" }
+ * - object: { expression: "0 8 * * *", timezone: "America/Chicago" }
+ * - object: { cron: "0 8 * * *" }
+ * - object: { value: "0 8 * * *" }
+ * - null/undefined/missing
+ */
+export function parseSchedule(raw: unknown): { expression: string; timezone: string | null } {
+  if (raw == null) return { expression: '', timezone: null }
+  if (typeof raw === 'string') return { expression: raw, timezone: null }
+  if (typeof raw === 'object') {
+    const obj = raw as Record<string, unknown>
+    const expression = String(obj.expr ?? obj.expression ?? obj.cron ?? obj.value ?? '')
+    const tz = obj.tz ?? obj.timezone
+    const timezone = typeof tz === 'string' ? tz : null
+    return { expression, timezone }
+  }
+  return { expression: String(raw), timezone: null }
+}
+
+/**
+ * Format a duration in milliseconds to a human-readable string.
+ * e.g. 147116 → "2m 27s", 45000 → "45s", 3600000 → "1h 0m"
+ */
+export function formatDuration(ms: number): string {
+  if (ms < 0 || !Number.isFinite(ms)) return '—'
+  const totalSec = Math.round(ms / 1000)
+  if (totalSec < 60) return `${totalSec}s`
+  const mins = Math.floor(totalSec / 60)
+  const secs = totalSec % 60
+  if (mins < 60) return secs > 0 ? `${mins}m ${secs}s` : `${mins}m`
+  const hrs = Math.floor(mins / 60)
+  const remMins = mins % 60
+  return `${hrs}h ${remMins}m`
+}
+
+/**
+ * Parse a 5-field cron expression into schedule slots for weekly grid display.
+ * Returns an array of { hour, minute, days } where days is 0=Sun..6=Sat.
+ * Returns null for unparseable expressions.
+ */
+export function parseScheduleSlots(expression: string): { hour: number; minute: number; days: number[] } | null {
+  if (!expression || !expression.trim()) return null
+  const parts = expression.trim().split(/\s+/)
+  if (parts.length !== 5) return null
+
+  const [min, hour, dom, , dow] = parts
+  const minNum = parseInt(min, 10)
+  const hourNum = parseInt(hour, 10)
+  if (isNaN(minNum) || isNaN(hourNum)) return null
+
+  let days: number[]
+
+  if (dow === '*') {
+    // Every day (or dom-based — treat as daily for weekly view)
+    days = [0, 1, 2, 3, 4, 5, 6]
+  } else if (dow === '1-5') {
+    days = [1, 2, 3, 4, 5]
+  } else if (dow === '0-6' || dow === '0,1,2,3,4,5,6') {
+    days = [0, 1, 2, 3, 4, 5, 6]
+  } else if (dow.includes(',')) {
+    days = dow.split(',').map(Number).filter(n => !isNaN(n) && n >= 0 && n <= 6)
+    if (days.length === 0) return null
+  } else {
+    const dowNum = parseInt(dow, 10)
+    if (isNaN(dowNum) || dowNum < 0 || dowNum > 6) return null
+    days = [dowNum]
+  }
+
+  return { hour: hourNum, minute: minNum, days }
+}
+
+/**
+ * Convert a 5-field cron expression to a human-readable description.
+ * Falls back to the raw expression for anything unparseable.
+ */
+export function describeCron(expression: string): string {
+  if (!expression || !expression.trim()) return ''
+
+  const parts = expression.trim().split(/\s+/)
+  if (parts.length !== 5) return expression
+
+  const [min, hour, dom, , dow] = parts
+
+  // Every minute: * * * * *
+  if (min === '*' && hour === '*' && dom === '*' && dow === '*') {
+    return 'Every minute'
+  }
+
+  // Every hour: 0 * * * *
+  if (min !== '*' && hour === '*' && dom === '*' && dow === '*') {
+    return 'Every hour'
+  }
+
+  const hourNum = parseInt(hour, 10)
+  const minNum = parseInt(min, 10)
+  if (isNaN(hourNum) || isNaN(minNum)) return expression
+
+  const time = minNum === 0 ? formatTime(hourNum, minNum) : formatTimeWithMinute(hourNum, minNum)
+
+  // Every N days: 0 12 */2 * *
+  if (dom.startsWith('*/') && dow === '*') {
+    const interval = parseInt(dom.slice(2), 10)
+    if (!isNaN(interval)) {
+      return `Every ${interval} days at ${time}`
+    }
+  }
+
+  // Monthly: 0 8 1 * *
+  if (dom !== '*' && dow === '*') {
+    const dayNum = parseInt(dom, 10)
+    if (!isNaN(dayNum)) {
+      const suffix = dayNum === 1 ? 'st' : dayNum === 2 ? 'nd' : dayNum === 3 ? 'rd' : 'th'
+      return `Monthly on the ${dayNum}${suffix} at ${time}`
+    }
+  }
+
+  // Weekdays: 0 10 * * 1-5
+  if (dom === '*' && dow === '1-5') {
+    return `Weekdays at ${time}`
+  }
+
+  // Specific day of week: 0 6 * * 1
+  if (dom === '*') {
+    const dowNum = parseInt(dow, 10)
+    if (!isNaN(dowNum) && dowNum >= 0 && dowNum <= 6) {
+      return `${DAY_NAMES[dowNum]} at ${time}`
+    }
+  }
+
+  // Daily: 0 8 * * *
+  if (dom === '*' && dow === '*') {
+    return `Daily at ${time}`
+  }
+
+  return expression
+}