clawport-ui 0.1.0

package/lib/crons.test.ts

@@ -0,0 +1,502 @@
+// @vitest-environment node
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+
+const { mockExecSync } = vi.hoisted(() => ({
+  mockExecSync: vi.fn(),
+}))
+
+// Mock child_process (Dependency Inversion -- no real CLI calls)
+vi.mock('child_process', () => ({
+  execSync: mockExecSync,
+  default: { execSync: mockExecSync },
+}))
+
+import { getCrons } from './crons'
+
+beforeEach(() => {
+  vi.clearAllMocks()
+  vi.stubEnv('OPENCLAW_BIN', '/usr/local/bin/openclaw')
+})
+
+// --- Well-formed data ---
+
+describe('getCrons - well-formed data', () => {
+  it('parses a flat array response', async () => {
+    const mockData = [
+      {
+        id: 'cron-1',
+        name: 'pulse-trending',
+        schedule: '0 8 * * *',
+        status: 'success',
+        state: {
+          nextRunAtMs: 1700000000000,
+          lastRunAtMs: 1699900000000,
+        },
+      },
+    ]
+    mockExecSync.mockReturnValue(JSON.stringify(mockData))
+
+    const crons = await getCrons()
+    expect(crons).toHaveLength(1)
+    expect(crons[0].id).toBe('cron-1')
+    expect(crons[0].name).toBe('pulse-trending')
+    expect(crons[0].schedule).toBe('0 8 * * *')
+    expect(crons[0].status).toBe('ok')
+    expect(crons[0].agentId).toBe('pulse')
+    expect(crons[0].nextRun).toBeTruthy()
+    expect(crons[0].lastRun).toBeTruthy()
+    expect(crons[0].lastError).toBeNull()
+  })
+
+  it('parses a { jobs: [...] } wrapper', async () => {
+    const mockData = {
+      jobs: [
+        {
+          id: 'cron-2',
+          name: 'seo-team-weekly',
+          schedule: '0 9 * * 1',
+          state: { status: 'ok' },
+        },
+      ],
+    }
+    mockExecSync.mockReturnValue(JSON.stringify(mockData))
+
+    const crons = await getCrons()
+    expect(crons).toHaveLength(1)
+    expect(crons[0].name).toBe('seo-team-weekly')
+    expect(crons[0].agentId).toBe('lumen')
+  })
+
+  it('parses a { data: [...] } wrapper', async () => {
+    const mockData = {
+      data: [
+        {
+          id: 'cron-3',
+          name: 'echo-reddit-scan',
+          schedule: '0 6 * * 0',
+          state: { status: 'completed' },
+        },
+      ],
+    }
+    mockExecSync.mockReturnValue(JSON.stringify(mockData))
+
+    const crons = await getCrons()
+    expect(crons).toHaveLength(1)
+    expect(crons[0].status).toBe('ok')
+    expect(crons[0].agentId).toBe('echo')
+  })
+
+  it('maps multiple crons to correct agents', async () => {
+    const mockData = [
+      { id: '1', name: 'pulse-daily', schedule: '0 8 * * *', state: {} },
+      { id: '2', name: 'herald-linkedin', schedule: '0 10 * * 1-5', state: {} },
+      { id: '3', name: 'kaze-flights', schedule: '0 7 * * *', state: {} },
+      { id: '4', name: 'spark-discover', schedule: '0 12 */2 * *', state: {} },
+      { id: '5', name: 'scribe-compress', schedule: '0 0 * * 0', state: {} },
+      { id: '6', name: 'robin-recon', schedule: '0 6 * * 1', state: {} },
+      { id: '7', name: 'vault-backup', schedule: '0 3 * * *', state: {} },
+      { id: '8', name: 'maven-calendar', schedule: '0 9 * * 1', state: {} },
+      { id: '9', name: 'team-memory-sync', schedule: '0 23 * * *', state: {} },
+      { id: '10', name: 'mochi-feed', schedule: '0 11 * * *', state: {} },
+    ]
+    mockExecSync.mockReturnValue(JSON.stringify(mockData))
+
+    const crons = await getCrons()
+    expect(crons).toHaveLength(10)
+
+    const agentMap: Record<string, string | null> = {}
+    for (const c of crons) agentMap[c.name] = c.agentId
+
+    expect(agentMap['pulse-daily']).toBe('pulse')
+    expect(agentMap['herald-linkedin']).toBe('herald')
+    expect(agentMap['kaze-flights']).toBe('kaze')
+    expect(agentMap['spark-discover']).toBe('spark')
+    expect(agentMap['scribe-compress']).toBe('scribe')
+    expect(agentMap['robin-recon']).toBe('robin')
+    expect(agentMap['vault-backup']).toBe('jarvis')
+    expect(agentMap['maven-calendar']).toBe('maven')
+    expect(agentMap['team-memory-sync']).toBe('scribe')
+    expect(agentMap['mochi-feed']).toBe('pulse')
+  })
+})
+
+// --- Status mapping ---
+
+describe('getCrons - status mapping', () => {
+  function makeCronWithStatus(status: string) {
+    return JSON.stringify([{
+      id: 'test',
+      name: 'pulse-test',
+      schedule: '* * * * *',
+      state: { status },
+    }])
+  }
+
+  it('maps "success" to "ok"', async () => {
+    mockExecSync.mockReturnValue(makeCronWithStatus('success'))
+    const crons = await getCrons()
+    expect(crons[0].status).toBe('ok')
+  })
+
+  it('maps "completed" to "ok"', async () => {
+    mockExecSync.mockReturnValue(makeCronWithStatus('completed'))
+    const crons = await getCrons()
+    expect(crons[0].status).toBe('ok')
+  })
+
+  it('maps "ok" to "ok"', async () => {
+    mockExecSync.mockReturnValue(makeCronWithStatus('ok'))
+    const crons = await getCrons()
+    expect(crons[0].status).toBe('ok')
+  })
+
+  it('maps "error" to "error"', async () => {
+    mockExecSync.mockReturnValue(makeCronWithStatus('error'))
+    const crons = await getCrons()
+    expect(crons[0].status).toBe('error')
+  })
+
+  it('maps "failed" to "error"', async () => {
+    mockExecSync.mockReturnValue(makeCronWithStatus('failed'))
+    const crons = await getCrons()
+    expect(crons[0].status).toBe('error')
+  })
+
+  it('maps unknown status to "idle"', async () => {
+    mockExecSync.mockReturnValue(makeCronWithStatus('pending'))
+    const crons = await getCrons()
+    expect(crons[0].status).toBe('idle')
+  })
+
+  it('maps empty string status to "idle"', async () => {
+    mockExecSync.mockReturnValue(makeCronWithStatus(''))
+    const crons = await getCrons()
+    expect(crons[0].status).toBe('idle')
+  })
+
+  it('reads status from top-level when state.status is missing', async () => {
+    mockExecSync.mockReturnValue(JSON.stringify([{
+      id: 'test',
+      name: 'pulse-test',
+      schedule: '* * * * *',
+      status: 'error',
+      state: {},
+    }]))
+    const crons = await getCrons()
+    expect(crons[0].status).toBe('error')
+  })
+})
+
+// --- Error / lastError ---
+
+describe('getCrons - error and lastError', () => {
+  it('captures lastError from state', async () => {
+    mockExecSync.mockReturnValue(JSON.stringify([{
+      id: 'test',
+      name: 'pulse-test',
+      schedule: '* * * * *',
+      state: { status: 'error', lastError: 'timeout after 10s' },
+    }]))
+    const crons = await getCrons()
+    expect(crons[0].lastError).toBe('timeout after 10s')
+  })
+
+  it('captures error from state.error fallback', async () => {
+    mockExecSync.mockReturnValue(JSON.stringify([{
+      id: 'test',
+      name: 'pulse-test',
+      schedule: '* * * * *',
+      state: { error: 'network failure' },
+    }]))
+    const crons = await getCrons()
+    expect(crons[0].lastError).toBe('network failure')
+  })
+
+  it('captures lastError from top-level', async () => {
+    mockExecSync.mockReturnValue(JSON.stringify([{
+      id: 'test',
+      name: 'pulse-test',
+      schedule: '* * * * *',
+      state: {},
+      lastError: 'out of memory',
+    }]))
+    const crons = await getCrons()
+    expect(crons[0].lastError).toBe('out of memory')
+  })
+
+  it('sets lastError to null when no error info present', async () => {
+    mockExecSync.mockReturnValue(JSON.stringify([{
+      id: 'test',
+      name: 'pulse-test',
+      schedule: '* * * * *',
+      state: {},
+    }]))
+    const crons = await getCrons()
+    expect(crons[0].lastError).toBeNull()
+  })
+})
+
+// --- Error propagation (current implementation throws) ---
+
+describe('getCrons - error propagation', () => {
+  it('throws when execSync throws (CLI not installed)', async () => {
+    mockExecSync.mockImplementation(() => { throw new Error('ENOENT') })
+    await expect(getCrons()).rejects.toThrow('Failed to fetch cron jobs')
+    await expect(getCrons()).rejects.toThrow('ENOENT')
+  })
+
+  it('throws for invalid JSON output', async () => {
+    mockExecSync.mockReturnValue('not valid json {{')
+    await expect(getCrons()).rejects.toThrow('Failed to fetch cron jobs')
+  })
+})
+
+// --- Schedule as object (bug fix: [object Object]) ---
+
+describe('getCrons - schedule object handling', () => {
+  it('parses schedule object with expression + timezone', async () => {
+    mockExecSync.mockReturnValue(JSON.stringify([{
+      id: 'cron-obj',
+      name: 'pulse-daily',
+      schedule: { expression: '0 8 * * *', timezone: 'America/Chicago' },
+      state: { status: 'ok' },
+    }]))
+    const crons = await getCrons()
+    expect(crons[0].schedule).toBe('0 8 * * *')
+    expect(crons[0].timezone).toBe('America/Chicago')
+    expect(crons[0].scheduleDescription).toBe('Daily at 8 AM')
+  })
+
+  it('parses schedule object with cron key', async () => {
+    mockExecSync.mockReturnValue(JSON.stringify([{
+      id: 'cron-obj2',
+      name: 'herald-linkedin',
+      schedule: { cron: '0 10 * * 1-5' },
+      state: { status: 'ok' },
+    }]))
+    const crons = await getCrons()
+    expect(crons[0].schedule).toBe('0 10 * * 1-5')
+    expect(crons[0].timezone).toBeNull()
+    expect(crons[0].scheduleDescription).toBe('Weekdays at 10 AM')
+  })
+
+  it('handles plain string schedule (no regression)', async () => {
+    mockExecSync.mockReturnValue(JSON.stringify([{
+      id: 'cron-str',
+      name: 'vault-backup',
+      schedule: '0 3 * * *',
+      state: { status: 'ok' },
+    }]))
+    const crons = await getCrons()
+    expect(crons[0].schedule).toBe('0 3 * * *')
+    expect(crons[0].timezone).toBeNull()
+    expect(crons[0].scheduleDescription).toBe('Daily at 3 AM')
+  })
+
+  it('handles missing schedule', async () => {
+    mockExecSync.mockReturnValue(JSON.stringify([{
+      id: 'cron-none',
+      name: 'pulse-test',
+      state: {},
+    }]))
+    const crons = await getCrons()
+    expect(crons[0].schedule).toBe('')
+    expect(crons[0].scheduleDescription).toBe('')
+    expect(crons[0].timezone).toBeNull()
+  })
+
+  it('never produces [object Object]', async () => {
+    mockExecSync.mockReturnValue(JSON.stringify([
+      { id: '1', name: 'a', schedule: { expression: '0 8 * * *' }, state: {} },
+      { id: '2', name: 'b', schedule: { cron: '* * * * *' }, state: {} },
+      { id: '3', name: 'c', schedule: 'plain string', state: {} },
+      { id: '4', name: 'd', state: {} },
+    ]))
+    const crons = await getCrons()
+    for (const cron of crons) {
+      expect(cron.schedule).not.toContain('[object Object]')
+      expect(cron.scheduleDescription).not.toContain('[object Object]')
+    }
+  })
+})
+
+// --- Graceful defaults for missing fields ---
+
+describe('getCrons - missing fields defaults', () => {
+  it('handles job with all fields missing (defaults to safe values)', async () => {
+    mockExecSync.mockReturnValue(JSON.stringify([{}]))
+    const crons = await getCrons()
+    expect(crons).toHaveLength(1)
+    expect(crons[0].id).toBe('')
+    expect(crons[0].name).toBe('')
+    expect(crons[0].schedule).toBe('')
+    expect(crons[0].scheduleDescription).toBe('')
+    expect(crons[0].timezone).toBeNull()
+    expect(crons[0].status).toBe('idle')
+    expect(crons[0].lastRun).toBeNull()
+    expect(crons[0].nextRun).toBeNull()
+    expect(crons[0].lastError).toBeNull()
+    expect(crons[0].agentId).toBeNull()
+  })
+
+  it('handles job with no state object', async () => {
+    mockExecSync.mockReturnValue(JSON.stringify([{
+      id: 'x',
+      name: 'pulse-test',
+      schedule: '0 * * * *',
+    }]))
+    const crons = await getCrons()
+    expect(crons).toHaveLength(1)
+    expect(crons[0].status).toBe('idle')
+  })
+
+  it('uses j.name as id fallback when j.id is missing', async () => {
+    mockExecSync.mockReturnValue(JSON.stringify([{
+      name: 'herald-post',
+      schedule: '0 10 * * *',
+      state: {},
+    }]))
+    const crons = await getCrons()
+    expect(crons[0].id).toBe('herald-post')
+  })
+
+  it('returns null agentId for unrecognized name prefix', async () => {
+    mockExecSync.mockReturnValue(JSON.stringify([{
+      id: 'unknown',
+      name: 'mystery-cron',
+      schedule: '0 0 * * *',
+      state: {},
+    }]))
+    const crons = await getCrons()
+    expect(crons[0].agentId).toBeNull()
+  })
+
+  it('defaults new fields when missing', async () => {
+    mockExecSync.mockReturnValue(JSON.stringify([{
+      id: 'test',
+      name: 'pulse-test',
+      schedule: '* * * * *',
+      state: {},
+    }]))
+    const crons = await getCrons()
+    expect(crons[0].description).toBeNull()
+    expect(crons[0].enabled).toBe(true)
+    expect(crons[0].delivery).toBeNull()
+    expect(crons[0].lastDurationMs).toBeNull()
+    expect(crons[0].consecutiveErrors).toBe(0)
+    expect(crons[0].lastDeliveryStatus).toBeNull()
+  })
+
+  it('handles empty array from CLI', async () => {
+    mockExecSync.mockReturnValue(JSON.stringify([]))
+    const crons = await getCrons()
+    expect(crons).toEqual([])
+  })
+
+  it('handles empty object from CLI (no jobs/data key)', async () => {
+    mockExecSync.mockReturnValue(JSON.stringify({}))
+    const crons = await getCrons()
+    expect(crons).toEqual([])
+  })
+})
+
+// --- Date parsing ---
+
+describe('getCrons - date parsing', () => {
+  it('converts nextRunAtMs (milliseconds) to ISO string', async () => {
+    const ts = 1700000000000
+    mockExecSync.mockReturnValue(JSON.stringify([{
+      id: 'test',
+      name: 'pulse-test',
+      schedule: '* * * * *',
+      state: { nextRunAtMs: ts },
+    }]))
+    const crons = await getCrons()
+    expect(crons[0].nextRun).toBe(new Date(ts).toISOString())
+  })
+
+  it('converts lastRunAtMs to ISO string', async () => {
+    const ts = 1699900000000
+    mockExecSync.mockReturnValue(JSON.stringify([{
+      id: 'test',
+      name: 'pulse-test',
+      schedule: '* * * * *',
+      state: { lastRunAtMs: ts },
+    }]))
+    const crons = await getCrons()
+    expect(crons[0].lastRun).toBe(new Date(ts).toISOString())
+  })
+
+  it('falls back to top-level nextRunAt', async () => {
+    const ts = 1700000000000
+    mockExecSync.mockReturnValue(JSON.stringify([{
+      id: 'test',
+      name: 'pulse-test',
+      schedule: '* * * * *',
+      state: {},
+      nextRunAt: ts,
+    }]))
+    const crons = await getCrons()
+    expect(crons[0].nextRun).toBe(new Date(ts).toISOString())
+  })
+})
+
+// --- Actual data format (expr/tz) + rich fields ---
+
+describe('getCrons - actual data format with expr/tz and rich fields', () => {
+  it('parses schedule with { kind: "cron", expr, tz }', async () => {
+    mockExecSync.mockReturnValue(JSON.stringify([{
+      id: '0b133350-ca33-42ae-a4b3-9b4d249e4a6b',
+      name: 'builder-briefing',
+      description: 'Daily 6 AM wake-up message for John with image',
+      enabled: true,
+      schedule: { kind: 'cron', expr: '0 6 * * *', tz: 'America/Chicago' },
+      delivery: { mode: 'announce', channel: 'discord', to: 'channel:1475355059721339063' },
+      state: {
+        lastRunStatus: 'ok',
+        lastDurationMs: 147116,
+        lastDelivered: true,
+        lastDeliveryStatus: 'delivered',
+        consecutiveErrors: 0,
+        nextRunAtMs: 1772539200000,
+        lastRunAtMs: 1772452800026,
+      },
+    }]))
+    const crons = await getCrons()
+    expect(crons[0].schedule).toBe('0 6 * * *')
+    expect(crons[0].timezone).toBe('America/Chicago')
+    expect(crons[0].scheduleDescription).toBe('Daily at 6 AM')
+    expect(crons[0].description).toBe('Daily 6 AM wake-up message for John with image')
+    expect(crons[0].enabled).toBe(true)
+    expect(crons[0].delivery).toEqual({ mode: 'announce', channel: 'discord', to: 'channel:1475355059721339063' })
+    expect(crons[0].lastDurationMs).toBe(147116)
+    expect(crons[0].consecutiveErrors).toBe(0)
+    expect(crons[0].lastDeliveryStatus).toBe('delivered')
+  })
+
+  it('handles delivery with missing to field', async () => {
+    mockExecSync.mockReturnValue(JSON.stringify([{
+      id: 'test',
+      name: 'vault-morning-snapshot',
+      schedule: { kind: 'cron', expr: '0 5 * * *', tz: 'America/Chicago' },
+      delivery: { mode: 'announce', channel: 'discord' },
+      state: { lastRunStatus: 'error', consecutiveErrors: 3, lastDeliveryStatus: 'unknown' },
+    }]))
+    const crons = await getCrons()
+    expect(crons[0].delivery).toEqual({ mode: 'announce', channel: 'discord', to: null })
+    expect(crons[0].consecutiveErrors).toBe(3)
+    expect(crons[0].lastDeliveryStatus).toBe('unknown')
+  })
+
+  it('handles disabled job', async () => {
+    mockExecSync.mockReturnValue(JSON.stringify([{
+      id: 'disabled',
+      name: 'test-disabled',
+      enabled: false,
+      schedule: '* * * * *',
+      state: {},
+    }]))
+    const crons = await getCrons()
+    expect(crons[0].enabled).toBe(false)
+  })
+})

package/lib/crons.ts

@@ -0,0 +1,114 @@
+import { CronJob, CronDelivery } from '@/lib/types'
+import { execSync } from 'child_process'
+import { parseSchedule, describeCron } from './cron-utils'
+import { requireEnv } from '@/lib/env'
+
+const PREFIX_MAP: [string, string][] = [
+  ['pulse-', 'pulse'],
+  ['herald-', 'herald'],
+  ['robin-', 'robin'],
+  ['seo-team-', 'lumen'],
+  ['seo-', 'lumen'],
+  ['echo-', 'echo'],
+  ['spark-', 'spark'],
+  ['scribe-', 'scribe'],
+  ['kaze-', 'kaze'],
+  ['vault-', 'jarvis'],
+  ['builder-', 'jarvis'],
+  ['clawport-', 'jarvis'],
+  ['maven-', 'maven'],
+  ['recon-', 'robin'],
+  ['team-memory-', 'scribe'],
+  ['mochi-', 'pulse'],
+]
+
+function matchAgent(name: string): string | null {
+  for (const [prefix, agentId] of PREFIX_MAP) {
+    if (name.startsWith(prefix)) return agentId
+  }
+  return null
+}
+
+export async function getCrons(): Promise<CronJob[]> {
+  try {
+    const openclawBin = requireEnv('OPENCLAW_BIN')
+    const raw = execSync(`${openclawBin} cron list --json`, {
+      encoding: 'utf-8',
+      timeout: 10000,
+    })
+
+    const parsed = JSON.parse(raw)
+    const jobs: unknown[] = Array.isArray(parsed)
+      ? parsed
+      : parsed.jobs ?? parsed.data ?? []
+
+    return jobs.map((job: unknown) => {
+      const j = job as Record<string, unknown>
+      const state = (j.state as Record<string, unknown>) || {}
+      const name = String(j.name || '')
+      const { expression: schedule, timezone } = parseSchedule(j.schedule)
+
+      // Status can be in state.status or directly on j.status
+      const rawStatus = state.status ?? j.status ?? ''
+      let status: 'ok' | 'error' | 'idle' = 'idle'
+      if (rawStatus === 'error' || rawStatus === 'failed') {
+        status = 'error'
+      } else if (rawStatus === 'ok' || rawStatus === 'success' || rawStatus === 'completed') {
+        status = 'ok'
+      }
+
+      // nextRun: try state.nextRunAtMs first, then state.nextRunAt
+      const nextRunMs = state.nextRunAtMs ?? state.nextRunAt ?? j.nextRunAtMs ?? j.nextRunAt
+      const nextRun = nextRunMs
+        ? new Date(Number(nextRunMs)).toISOString()
+        : null
+
+      // lastRun: try state.lastRunAtMs, state.lastRunAt, or top-level equivalents
+      const lastRunRaw = state.lastRunAtMs ?? state.lastRunAt ?? j.lastRunAtMs ?? j.lastRunAt ?? j.last
+      const lastRun = lastRunRaw
+        ? (typeof lastRunRaw === 'number' ? new Date(lastRunRaw).toISOString() : String(lastRunRaw))
+        : null
+
+      const lastError = (state.lastError ?? state.error ?? j.lastError) ? String(state.lastError ?? state.error ?? j.lastError) : null
+
+      // Delivery config
+      const rawDelivery = j.delivery as Record<string, unknown> | undefined
+      let delivery: CronDelivery | null = null
+      if (rawDelivery && typeof rawDelivery === 'object') {
+        delivery = {
+          mode: String(rawDelivery.mode || ''),
+          channel: String(rawDelivery.channel || ''),
+          to: rawDelivery.to ? String(rawDelivery.to) : null,
+        }
+      }
+
+      // Rich state fields
+      const lastDurationMs = typeof state.lastDurationMs === 'number' ? state.lastDurationMs : null
+      const consecutiveErrors = typeof state.consecutiveErrors === 'number' ? state.consecutiveErrors : 0
+      const lastDeliveryStatus = typeof state.lastDeliveryStatus === 'string' ? state.lastDeliveryStatus : null
+
+      return {
+        id: String(j.id || j.name || ''),
+        name,
+        schedule,
+        scheduleDescription: describeCron(schedule),
+        timezone,
+        status,
+        lastRun,
+        nextRun,
+        lastError,
+        agentId: matchAgent(name),
+        description: typeof j.description === 'string' ? j.description : null,
+        enabled: j.enabled !== false,
+        delivery,
+        lastDurationMs,
+        consecutiveErrors,
+        lastDeliveryStatus,
+      }
+    })
+  } catch (err) {
+    throw new Error(
+      `Failed to fetch cron jobs: ${err instanceof Error ? err.message : String(err)}`
+    )
+  }
+}

package/lib/env.test.ts

@@ -0,0 +1,44 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import { requireEnv } from '@/lib/env'
+
+describe('requireEnv', () => {
+  beforeEach(() => {
+    vi.unstubAllEnvs()
+  })
+
+  afterEach(() => {
+    vi.unstubAllEnvs()
+  })
+
+  it('returns the value when the environment variable is set', () => {
+    vi.stubEnv('TEST_VAR', '/some/path')
+    expect(requireEnv('TEST_VAR')).toBe('/some/path')
+  })
+
+  it('throws when the environment variable is missing', () => {
+    delete process.env.TEST_MISSING_VAR
+    expect(() => requireEnv('TEST_MISSING_VAR')).toThrow()
+  })
+
+  it('throws when the environment variable is an empty string', () => {
+    vi.stubEnv('TEST_EMPTY_VAR', '')
+    expect(() => requireEnv('TEST_EMPTY_VAR')).toThrow()
+  })
+
+  it('error message includes the variable name', () => {
+    delete process.env.MY_SPECIAL_VAR
+    expect(() => requireEnv('MY_SPECIAL_VAR')).toThrow('MY_SPECIAL_VAR')
+  })
+
+  it('error message mentions .env.example', () => {
+    delete process.env.SOME_VAR
+    expect(() => requireEnv('SOME_VAR')).toThrow('.env.example')
+  })
+
+  it('error message includes "Missing required environment variable"', () => {
+    delete process.env.ANOTHER_VAR
+    expect(() => requireEnv('ANOTHER_VAR')).toThrow(
+      'Missing required environment variable: ANOTHER_VAR'
+    )
+  })
+})

package/lib/env.ts

@@ -0,0 +1,14 @@
+/**
+ * Safely retrieve a required environment variable at runtime.
+ * Call inside functions (not at module top level) so imports don't crash during build/test.
+ */
+export function requireEnv(name: string): string {
+  const value = process.env[name]
+  if (!value) {
+    throw new Error(
+      `Missing required environment variable: ${name}. ` +
+      `See .env.example for configuration.`
+    )
+  }
+  return value
+}