@marcusrbrown/infra 0.1.0 → 0.3.0

package/src/commands/cliproxy-status.test.ts

@@ -0,0 +1,271 @@
+import {afterEach, beforeEach, describe, expect, it} from 'bun:test'
+
+import {
+  checkHttpReachability,
+  checkUsageStats,
+  checkVersion,
+  formatDurationMs,
+  levelLabel,
+  stripTrailingSlash,
+  toNumber,
+} from './cliproxy-status'
+
+const originalFetch = globalThis.fetch
+
+type FetchReplacement = (url: string, init?: RequestInit) => Promise<Response>
+
+function createFetchImplementation(handler: FetchReplacement): typeof fetch {
+  return Object.assign(
+    (input: string | URL | Request, init?: RequestInit) => {
+      if (typeof input !== 'string') {
+        throw new TypeError(`Unexpected non-string fetch input: ${String(input)}`)
+      }
+
+      return handler(input, init)
+    },
+    {preconnect: originalFetch.preconnect},
+  )
+}
+
+describe('cliproxy status helpers', () => {
+  beforeEach(() => {
+    globalThis.fetch = createFetchImplementation(async () => {
+      throw new Error('Unexpected fetch call')
+    })
+  })
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch
+  })
+
+  describe('levelLabel', () => {
+    it('returns OK for ok', () => {
+      expect(levelLabel('ok')).toBe('OK')
+    })
+
+    it('returns WARN for warning', () => {
+      expect(levelLabel('warning')).toBe('WARN')
+    })
+
+    it('returns ERROR for error', () => {
+      expect(levelLabel('error')).toBe('ERROR')
+    })
+  })
+
+  describe('formatDurationMs', () => {
+    it('formats positive durations', () => {
+      expect(formatDurationMs(150)).toBe('150ms')
+    })
+
+    it('formats zero duration', () => {
+      expect(formatDurationMs(0)).toBe('0ms')
+    })
+
+    it('clamps negative durations to zero', () => {
+      expect(formatDurationMs(-5)).toBe('0ms')
+    })
+  })
+
+  describe('stripTrailingSlash', () => {
+    it('removes a trailing slash', () => {
+      expect(stripTrailingSlash('https://example.com/')).toBe('https://example.com')
+    })
+
+    it('does nothing when there is no trailing slash', () => {
+      expect(stripTrailingSlash('https://example.com')).toBe('https://example.com')
+    })
+  })
+
+  describe('toNumber', () => {
+    it('returns finite numbers as-is', () => {
+      expect(toNumber(42)).toBe(42)
+    })
+
+    it('returns null for non-numbers', () => {
+      expect(toNumber('not a number')).toBeNull()
+    })
+
+    it('returns null for NaN', () => {
+      expect(toNumber(Number.NaN)).toBeNull()
+    })
+
+    it('returns null for infinity', () => {
+      expect(toNumber(Number.POSITIVE_INFINITY)).toBeNull()
+    })
+  })
+
+  describe('checkHttpReachability', () => {
+    it('returns ok for HTTP 200', async () => {
+      globalThis.fetch = createFetchImplementation(async () => new Response('ok', {status: 200}))
+
+      const result = await checkHttpReachability('https://cliproxy.example.com', false)
+
+      expect(result.level).toBe('ok')
+      expect(result.summary).toContain('GET https://cliproxy.example.com → 200')
+      expect(result.summary).toContain('ms')
+    })
+
+    it('returns error for HTTP 500', async () => {
+      globalThis.fetch = createFetchImplementation(async () => new Response('error', {status: 500}))
+
+      const result = await checkHttpReachability('https://cliproxy.example.com', false)
+
+      expect(result.level).toBe('error')
+      expect(result.summary).toContain('GET https://cliproxy.example.com → 500')
+    })
+
+    it('returns error details for network failures', async () => {
+      globalThis.fetch = createFetchImplementation(async () => {
+        throw new Error('Network timeout')
+      })
+
+      const result = await checkHttpReachability('https://cliproxy.example.com', true)
+
+      expect(result.level).toBe('error')
+      expect(result.summary).toContain('Network timeout')
+      expect(result.details).toEqual(['URL: https://cliproxy.example.com', 'Timeout: 10000ms'])
+    })
+  })
+
+  describe('checkUsageStats', () => {
+    it('returns ok when failures are zero', async () => {
+      globalThis.fetch = createFetchImplementation(
+        async () =>
+          new Response(JSON.stringify({total_requests: 10, failure_count: 0}), {
+            status: 200,
+            headers: {'content-type': 'application/json'},
+          }),
+      )
+
+      const result = await checkUsageStats('https://cliproxy.example.com', 'secret')
+
+      expect(result.level).toBe('ok')
+      expect(result.summary).toBe('total_requests=10, failure_count=0')
+    })
+
+    it('returns warning when token refresh is likely needed', async () => {
+      globalThis.fetch = createFetchImplementation(
+        async () =>
+          new Response(JSON.stringify({total_requests: 10, failure_count: 3}), {
+            status: 200,
+            headers: {'content-type': 'application/json'},
+          }),
+      )
+
+      const result = await checkUsageStats('https://cliproxy.example.com', 'secret')
+
+      expect(result.level).toBe('warning')
+      expect(result.summary).toContain('total_requests=10, failure_count=3')
+      expect(result.summary).toContain('token refresh likely needed')
+    })
+
+    it('returns warning when rate limited', async () => {
+      globalThis.fetch = createFetchImplementation(async () => new Response('rate limited', {status: 429}))
+
+      const result = await checkUsageStats('https://cliproxy.example.com', 'secret')
+
+      expect(result.level).toBe('warning')
+      expect(result.summary).toContain('Rate limited')
+    })
+
+    it('returns error for non-200 responses', async () => {
+      globalThis.fetch = createFetchImplementation(async () => new Response('boom', {status: 500}))
+
+      const result = await checkUsageStats('https://cliproxy.example.com', 'secret')
+
+      expect(result.level).toBe('error')
+      expect(result.summary).toContain('HTTP 500')
+    })
+
+    it('returns error for network failures', async () => {
+      globalThis.fetch = createFetchImplementation(async () => {
+        throw new Error('socket hang up')
+      })
+
+      const result = await checkUsageStats('https://cliproxy.example.com', 'secret')
+
+      expect(result.level).toBe('error')
+      expect(result.summary).toContain('Unable to read usage stats: socket hang up')
+    })
+  })
+
+  describe('checkVersion', () => {
+    it('returns ok for JSON string payloads', async () => {
+      globalThis.fetch = createFetchImplementation(
+        async () =>
+          new Response(JSON.stringify('1.2.3'), {
+            status: 200,
+            headers: {'content-type': 'application/json'},
+          }),
+      )
+
+      const result = await checkVersion('https://cliproxy.example.com', 'secret')
+
+      expect(result.level).toBe('ok')
+      expect(result.summary).toBe('1.2.3')
+    })
+
+    it('returns ok for object payloads with version', async () => {
+      globalThis.fetch = createFetchImplementation(
+        async () =>
+          new Response(JSON.stringify({version: '1.2.3'}), {
+            status: 200,
+            headers: {'content-type': 'application/json'},
+          }),
+      )
+
+      const result = await checkVersion('https://cliproxy.example.com', 'secret')
+
+      expect(result.level).toBe('ok')
+      expect(result.summary).toBe('1.2.3')
+    })
+
+    it('returns warning for empty version strings', async () => {
+      globalThis.fetch = createFetchImplementation(
+        async () =>
+          new Response(JSON.stringify({version: ''}), {
+            status: 200,
+            headers: {'content-type': 'application/json'},
+          }),
+      )
+
+      const result = await checkVersion('https://cliproxy.example.com', 'secret')
+
+      expect(result.level).toBe('warning')
+      expect(result.summary).toContain('did not include a usable version string')
+    })
+
+    it('returns warning for missing version fields', async () => {
+      globalThis.fetch = createFetchImplementation(
+        async () =>
+          new Response(JSON.stringify({}), {
+            status: 200,
+            headers: {'content-type': 'application/json'},
+          }),
+      )
+
+      const result = await checkVersion('https://cliproxy.example.com', 'secret')
+
+      expect(result.level).toBe('warning')
+      expect(result.summary).toContain('did not include a usable version string')
+    })
+
+    it('returns warning when rate limited', async () => {
+      globalThis.fetch = createFetchImplementation(async () => new Response('rate limited', {status: 429}))
+
+      const result = await checkVersion('https://cliproxy.example.com', 'secret')
+
+      expect(result.level).toBe('warning')
+      expect(result.summary).toContain('Rate limited')
+    })
+
+    it('returns error for non-200 responses', async () => {
+      globalThis.fetch = createFetchImplementation(async () => new Response('boom', {status: 500}))
+
+      const result = await checkVersion('https://cliproxy.example.com', 'secret')
+
+      expect(result.level).toBe('error')
+      expect(result.summary).toContain('HTTP 500')
+    })
+  })
+})

package/src/commands/cliproxy-status.ts

@@ -0,0 +1,274 @@
+import type {goke} from 'goke'
+
+import {z} from 'zod'
+
+const DEFAULT_CLIPROXY_URL = 'https://cliproxy.fro.bot'
+const HTTP_TIMEOUT_MS = 10_000
+
+type CheckLevel = 'ok' | 'warning' | 'error'
+
+interface CheckResult {
+  title: string
+  level: CheckLevel
+  summary: string
+  details?: string[]
+}
+
+export function levelLabel(level: CheckLevel): string {
+  if (level === 'ok') {
+    return 'OK'
+  }
+
+  if (level === 'warning') {
+    return 'WARN'
+  }
+
+  return 'ERROR'
+}
+
+export function formatDurationMs(durationMs: number): string {
+  return `${Math.max(0, Math.round(durationMs))}ms`
+}
+
+export function stripTrailingSlash(value: string): string {
+  return value.endsWith('/') ? value.slice(0, -1) : value
+}
+
+function managementHeaders(key: string): Headers {
+  const headers = new Headers()
+  headers.set('authorization', `Bearer ${key}`)
+  headers.set('x-management-key', key)
+  return headers
+}
+
+async function parseJsonResponse(response: Response): Promise<unknown> {
+  try {
+    return await response.json()
+  } catch {
+    return null
+  }
+}
+
+export function toNumber(value: unknown): number | null {
+  return typeof value === 'number' && Number.isFinite(value) ? value : null
+}
+
+export async function checkHttpReachability(url: string, verbose: boolean): Promise<CheckResult> {
+  const startedAt = performance.now()
+
+  try {
+    const response = await fetch(url, {
+      signal: AbortSignal.timeout(HTTP_TIMEOUT_MS),
+    })
+    const elapsedMs = performance.now() - startedAt
+    const details: string[] = []
+
+    if (verbose) {
+      details.push(`URL: ${url}`)
+      details.push(`Status text: ${response.statusText || '(none)'}`)
+      if (response.headers.get('content-type')) {
+        details.push(`Content-Type: ${response.headers.get('content-type')}`)
+      }
+    }
+
+    return {
+      title: 'HTTP reachability',
+      level: response.ok ? 'ok' : 'error',
+      summary: `GET ${url} → ${response.status} (${formatDurationMs(elapsedMs)})`,
+      details,
+    }
+  } catch (error) {
+    const elapsedMs = performance.now() - startedAt
+    const message = error instanceof Error ? error.message : String(error)
+
+    return {
+      title: 'HTTP reachability',
+      level: 'error',
+      summary: `Request failed after ${formatDurationMs(elapsedMs)}: ${message}`,
+      details: verbose ? [`URL: ${url}`, `Timeout: ${HTTP_TIMEOUT_MS}ms`] : undefined,
+    }
+  }
+}
+
+export async function checkUsageStats(baseUrl: string, key: string): Promise<CheckResult> {
+  const endpoint = `${baseUrl}/v0/management/usage`
+
+  try {
+    const response = await fetch(endpoint, {
+      headers: managementHeaders(key),
+      signal: AbortSignal.timeout(HTTP_TIMEOUT_MS),
+    })
+
+    if (response.status === 429) {
+      return {
+        title: 'Usage stats',
+        level: 'warning',
+        summary: 'Rate limited by management API (HTTP 429). Retry in a few moments.',
+      }
+    }
+
+    if (!response.ok) {
+      return {
+        title: 'Usage stats',
+        level: 'error',
+        summary: `GET /v0/management/usage failed with HTTP ${response.status}`,
+      }
+    }
+
+    const payload = await parseJsonResponse(response)
+    const record = payload && typeof payload === 'object' ? payload : {}
+    const totalRequests = toNumber((record as Record<string, unknown>).total_requests)
+    const failureCount = toNumber((record as Record<string, unknown>).failure_count)
+
+    if (totalRequests === null || failureCount === null) {
+      return {
+        title: 'Usage stats',
+        level: 'warning',
+        summary: 'Management usage payload is missing expected numeric fields.',
+      }
+    }
+
+    return {
+      title: 'Usage stats',
+      level: failureCount > 0 ? 'warning' : 'ok',
+      summary:
+        failureCount > 0
+          ? `total_requests=${totalRequests}, failure_count=${failureCount} (token refresh likely needed)`
+          : `total_requests=${totalRequests}, failure_count=${failureCount}`,
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error)
+    return {
+      title: 'Usage stats',
+      level: 'error',
+      summary: `Unable to read usage stats: ${message}`,
+    }
+  }
+}
+
+export async function checkVersion(baseUrl: string, key: string): Promise<CheckResult> {
+  const endpoint = `${baseUrl}/v0/management/latest-version`
+
+  try {
+    const response = await fetch(endpoint, {
+      headers: managementHeaders(key),
+      signal: AbortSignal.timeout(HTTP_TIMEOUT_MS),
+    })
+
+    if (response.status === 429) {
+      return {
+        title: 'Current version',
+        level: 'warning',
+        summary: 'Rate limited by management API (HTTP 429). Retry in a few moments.',
+      }
+    }
+
+    if (!response.ok) {
+      return {
+        title: 'Current version',
+        level: 'error',
+        summary: `GET /v0/management/latest-version failed with HTTP ${response.status}`,
+      }
+    }
+
+    const payload = await parseJsonResponse(response)
+
+    if (typeof payload === 'string' && payload.length > 0) {
+      return {
+        title: 'Current version',
+        level: 'ok',
+        summary: payload,
+      }
+    }
+
+    if (payload && typeof payload === 'object') {
+      const version = (payload as Record<string, unknown>).version
+      if (typeof version === 'string' && version.length > 0) {
+        return {
+          title: 'Current version',
+          level: 'ok',
+          summary: version,
+        }
+      }
+    }
+
+    return {
+      title: 'Current version',
+      level: 'warning',
+      summary: 'Management version payload did not include a usable version string.',
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error)
+    return {
+      title: 'Current version',
+      level: 'error',
+      summary: `Unable to read current version: ${message}`,
+    }
+  }
+}
+
+function printCheckResult(result: CheckResult): void {
+  console.log(`[${levelLabel(result.level)}] ${result.title}`)
+  console.log(`  ${result.summary}`)
+
+  if (result.details && result.details.length > 0) {
+    for (const detail of result.details) {
+      console.log(`  - ${detail}`)
+    }
+  }
+}
+
+export function registerCliproxyStatus(cli: ReturnType<typeof goke>): void {
+  cli
+    .command('cliproxy status', 'Show operational health of CLIProxyAPI and its management endpoints.')
+    .option(
+      '--url [url]',
+      z
+        .string()
+        .describe('Base URL for CLIProxyAPI health checks. Falls back to CLIPROXY_URL or https://cliproxy.fro.bot.'),
+    )
+    .option(
+      '--key [key]',
+      z.string().describe('Management API bearer token. Falls back to CLIPROXY_MANAGEMENT_KEY when omitted.'),
+    )
+    .action(async options => {
+      const verbose = options.verbose === true
+      const baseUrl = stripTrailingSlash(options.url ?? process.env.CLIPROXY_URL ?? DEFAULT_CLIPROXY_URL)
+      const managementKey = options.key ?? process.env.CLIPROXY_MANAGEMENT_KEY
+
+      console.log('CLIProxyAPI status')
+      console.log('')
+
+      const results: CheckResult[] = [await checkHttpReachability(baseUrl, verbose)]
+
+      if (managementKey) {
+        const [usageResult, versionResult] = await Promise.all([
+          checkUsageStats(baseUrl, managementKey),
+          checkVersion(baseUrl, managementKey),
+        ])
+
+        results.push(usageResult, versionResult)
+      } else {
+        results.push({
+          title: 'Management checks',
+          level: 'warning',
+          summary:
+            'CLIPROXY_MANAGEMENT_KEY is not set. Skipping usage stats and version checks. Provide --key or set env var.',
+        })
+      }
+
+      for (const result of results) {
+        printCheckResult(result)
+        console.log('')
+      }
+
+      const errorCount = results.filter(result => result.level === 'error').length
+      const warningCount = results.filter(result => result.level === 'warning').length
+
+      console.log(`Summary: ${results.length} checks, ${errorCount} errors, ${warningCount} warnings`)
+
+      if (errorCount > 0) {
+        process.exitCode = 1
+      }
+    })
+}