@marcusrbrown/infra 0.8.1 → 0.9.1

package/src/commands/umami/status.test.ts

@@ -0,0 +1,387 @@
+import {afterEach, beforeEach, describe, expect, it} from 'bun:test'
+
+import {createCapturedCtx, MockProcessExit} from '../../__test__/mcp-ctx-fixture'
+import {
+  getUmamiComposeStatus,
+  getUmamiStatusSummary,
+  parseComposePs,
+  parseComposePsOutput,
+  umamiStatusAction,
+  type ComposePsEntry,
+  type ServiceRow,
+} from './status'
+
+// ─── parseComposePsOutput ─────────────────────────────────────────────────────
+
+describe('parseComposePsOutput', () => {
+  it('parses NDJSON output (one JSON object per line)', () => {
+    const ndjson = [
+      JSON.stringify({Name: 'umami', State: 'running', Health: 'healthy'}),
+      JSON.stringify({Name: 'db', State: 'running', Health: ''}),
+    ].join('\n')
+
+    const entries = parseComposePsOutput(ndjson)
+
+    expect(entries).toHaveLength(2)
+    expect(entries[0]).toEqual({Name: 'umami', State: 'running', Health: 'healthy'})
+    expect(entries[1]).toEqual({Name: 'db', State: 'running', Health: ''})
+  })
+
+  it('parses JSON-array output (legacy compose format)', () => {
+    const jsonArray = JSON.stringify([
+      {Name: 'umami', State: 'running', Health: 'healthy'},
+      {Name: 'db', State: 'running', Health: ''},
+    ])
+
+    const entries = parseComposePsOutput(jsonArray)
+
+    expect(entries).toHaveLength(2)
+    expect(entries[0]).toEqual({Name: 'umami', State: 'running', Health: 'healthy'})
+  })
+
+  it('returns empty array for empty string', () => {
+    expect(parseComposePsOutput('')).toEqual([])
+  })
+
+  it('returns empty array for whitespace-only string', () => {
+    expect(parseComposePsOutput('   \n  ')).toEqual([])
+  })
+})
+
+// ─── parseComposePs ──────────────────────────────────────────────────────────
+
+describe('parseComposePs', () => {
+  it('maps running services with healthy status', () => {
+    const raw: ComposePsEntry[] = [
+      {Name: 'umami', State: 'running', Health: 'healthy'},
+      {Name: 'db', State: 'running', Health: ''},
+    ]
+
+    const rows = parseComposePs(raw)
+
+    expect(rows).toHaveLength(2)
+    expect(rows[0]).toEqual({service: 'umami', state: 'running', health: 'healthy'} satisfies ServiceRow)
+    expect(rows[1]).toEqual({service: 'db', state: 'running', health: 'n-a'} satisfies ServiceRow)
+  })
+
+  it('maps exited state', () => {
+    const raw: ComposePsEntry[] = [{Name: 'umami', State: 'exited', Health: ''}]
+
+    const rows = parseComposePs(raw)
+
+    expect(rows[0]).toEqual({service: 'umami', state: 'exited', health: 'n-a'} satisfies ServiceRow)
+  })
+
+  it('maps unhealthy health status', () => {
+    const raw: ComposePsEntry[] = [{Name: 'umami', State: 'running', Health: 'unhealthy'}]
+
+    const rows = parseComposePs(raw)
+
+    expect(rows[0]?.health).toBe('unhealthy')
+  })
+
+  it('maps starting health status', () => {
+    const raw: ComposePsEntry[] = [{Name: 'umami', State: 'running', Health: 'starting'}]
+
+    const rows = parseComposePs(raw)
+
+    expect(rows[0]?.health).toBe('starting')
+  })
+
+  it('maps unknown health values to n-a', () => {
+    const raw: ComposePsEntry[] = [{Name: 'umami', State: 'running', Health: 'something-weird'}]
+
+    const rows = parseComposePs(raw)
+
+    expect(rows[0]?.health).toBe('n-a')
+  })
+
+  it('returns empty array for empty input', () => {
+    expect(parseComposePs([])).toEqual([])
+  })
+})
+
+// ─── getUmamiComposeStatus (SSH mocked via SpawnFn) ──────────────────────────
+
+type SpawnFn = (
+  cmd: string[],
+  opts: {env: Record<string, string>; stdout: 'pipe'; stderr: 'pipe'},
+) => {
+  stdout: ReadableStream<Uint8Array>
+  stderr: ReadableStream<Uint8Array>
+  exited: Promise<number>
+}
+
+function makeSpawn(stdout: string, stderr = '', exitCode = 0): SpawnFn {
+  return (_cmd, _opts) => {
+    const enc = new TextEncoder()
+    return {
+      stdout: new ReadableStream({
+        start(controller) {
+          controller.enqueue(enc.encode(stdout))
+          controller.close()
+        },
+      }),
+      stderr: new ReadableStream({
+        start(controller) {
+          controller.enqueue(enc.encode(stderr))
+          controller.close()
+        },
+      }),
+      exited: Promise.resolve(exitCode),
+    }
+  }
+}
+
+describe('getUmamiComposeStatus', () => {
+  it('returns service rows from NDJSON output', async () => {
+    const ndjson = [
+      JSON.stringify({Name: 'umami', State: 'running', Health: 'healthy'}),
+      JSON.stringify({Name: 'db', State: 'running', Health: ''}),
+    ].join('\n')
+
+    const result = await getUmamiComposeStatus('metrics.fro.bot', makeSpawn(ndjson))
+
+    expect(result.ok).toBe(true)
+    expect(result.services).toHaveLength(2)
+    expect(result.services[0]?.service).toBe('umami')
+  })
+
+  it('returns service rows from JSON-array output', async () => {
+    const jsonArray = JSON.stringify([
+      {Name: 'umami', State: 'running', Health: 'healthy'},
+      {Name: 'db', State: 'running', Health: ''},
+    ])
+
+    const result = await getUmamiComposeStatus('metrics.fro.bot', makeSpawn(jsonArray))
+
+    expect(result.ok).toBe(true)
+    expect(result.services).toHaveLength(2)
+  })
+
+  it('returns ok=false when SSH exits non-zero', async () => {
+    const result = await getUmamiComposeStatus('metrics.fro.bot', makeSpawn('', 'connection refused', 1))
+
+    expect(result.ok).toBe(false)
+    expect(result.error).toContain('SSH command failed')
+  })
+
+  it('rejects invalid host before spawning SSH', async () => {
+    let spawnCalled = false
+    const spy: SpawnFn = (cmd, opts) => {
+      spawnCalled = true
+      return makeSpawn('')(cmd, opts)
+    }
+
+    await expect(getUmamiComposeStatus('-oProxyCommand=evil', spy)).rejects.toThrow('Invalid UMAMI_DOMAIN')
+    expect(spawnCalled).toBe(false)
+  })
+})
+
+// ─── getUmamiStatusSummary ────────────────────────────────────────────────────
+
+describe('getUmamiStatusSummary', () => {
+  it('shows service rows with DEGRADED marker when services present but unhealthy', async () => {
+    const ndjson = [
+      JSON.stringify({Name: 'umami', State: 'running', Health: 'unhealthy'}),
+      JSON.stringify({Name: 'db', State: 'running', Health: 'healthy'}),
+    ].join('\n')
+
+    const summary = await getUmamiStatusSummary('metrics.fro.bot', makeSpawn(ndjson))
+
+    expect(summary.http).toContain('DEGRADED')
+    expect(summary.http).toContain('umami')
+    expect(summary.http).not.toContain('No services reported')
+  })
+
+  it('shows ERROR with no-services message when compose ps returns empty output', async () => {
+    const summary = await getUmamiStatusSummary('metrics.fro.bot', makeSpawn(''))
+
+    expect(summary.http).toContain('ERROR')
+    expect(summary.http).toContain('No services')
+    expect(summary.http).not.toContain('DEGRADED')
+  })
+
+  it('shows OK with service rows when all services are healthy', async () => {
+    const ndjson = [
+      JSON.stringify({Name: 'umami', State: 'running', Health: 'healthy'}),
+      JSON.stringify({Name: 'db', State: 'running', Health: 'healthy'}),
+    ].join('\n')
+
+    const summary = await getUmamiStatusSummary('metrics.fro.bot', makeSpawn(ndjson))
+
+    expect(summary.http).toContain('OK')
+    expect(summary.http).toContain('umami')
+    expect(summary.http).not.toContain('DEGRADED')
+    expect(summary.http).not.toContain('ERROR')
+  })
+})
+
+// ─── umamiStatusAction ───────────────────────────────────────────────────────
+
+describe('status command', () => {
+  let originalEnv: Record<string, string | undefined>
+
+  beforeEach(() => {
+    originalEnv = {UMAMI_DOMAIN: process.env.UMAMI_DOMAIN, MY_UMAMI_HOST: process.env.MY_UMAMI_HOST}
+  })
+
+  afterEach(() => {
+    if (originalEnv.UMAMI_DOMAIN === undefined) {
+      delete process.env.UMAMI_DOMAIN
+    } else {
+      process.env.UMAMI_DOMAIN = originalEnv.UMAMI_DOMAIN
+    }
+
+    if (originalEnv.MY_UMAMI_HOST === undefined) {
+      delete process.env.MY_UMAMI_HOST
+    } else {
+      process.env.MY_UMAMI_HOST = originalEnv.MY_UMAMI_HOST
+    }
+  })
+
+  it('outputs service rows through ctx when services are running', async () => {
+    process.env.UMAMI_DOMAIN = 'metrics.fro.bot'
+
+    const ndjson = [
+      JSON.stringify({Name: 'umami', State: 'running', Health: 'healthy'}),
+      JSON.stringify({Name: 'db', State: 'running', Health: ''}),
+    ].join('\n')
+
+    const {ctx, captured} = createCapturedCtx()
+
+    await umamiStatusAction({}, ctx, makeSpawn(ndjson))
+
+    const output = captured.stdout.join('\n')
+    expect(output).toContain('umami')
+    expect(output).toContain('running')
+    expect(captured.exit).toBeNull()
+  })
+
+  it('calls ctx.console.error and ctx.process.exit(1) on SSH failure without throwing', async () => {
+    process.env.UMAMI_DOMAIN = 'metrics.fro.bot'
+
+    const {ctx, captured} = createCapturedCtx()
+
+    let threw = false
+    try {
+      await umamiStatusAction({}, ctx, makeSpawn('', 'connection refused', 1))
+    } catch (error) {
+      if (error instanceof MockProcessExit) {
+        // expected — MockProcessExit is thrown by ctx.process.exit
+      } else {
+        threw = true
+      }
+    }
+
+    expect(threw).toBe(false)
+    expect(captured.stderr.join('')).toContain('Error')
+    expect(captured.exit?.code).toBe(1)
+  })
+
+  it('calls ctx.console.error and exits when UMAMI_DOMAIN is not set', async () => {
+    delete process.env.UMAMI_DOMAIN
+
+    const {ctx, captured} = createCapturedCtx()
+
+    try {
+      await umamiStatusAction({}, ctx)
+    } catch (error) {
+      if (!(error instanceof MockProcessExit)) throw error
+    }
+
+    expect(captured.stderr.join('')).toContain('UMAMI_DOMAIN')
+    expect(captured.exit?.code).toBe(1)
+  })
+
+  it('rejects bad host via ctx.console.error without throwing unhandled', async () => {
+    process.env.UMAMI_DOMAIN = '-oProxyCommand=evil'
+
+    const {ctx, captured} = createCapturedCtx()
+
+    try {
+      await umamiStatusAction({}, ctx, makeSpawn(''))
+    } catch (error) {
+      if (!(error instanceof MockProcessExit)) throw error
+    }
+
+    expect(captured.stderr.join('')).toContain('Invalid UMAMI_DOMAIN')
+    expect(captured.exit?.code).toBe(1)
+  })
+
+  it('reads host from the env var named by --key instead of UMAMI_DOMAIN', async () => {
+    delete process.env.UMAMI_DOMAIN
+    process.env.MY_UMAMI_HOST = 'metrics.fro.bot'
+
+    const ndjson = [
+      JSON.stringify({Name: 'umami', State: 'running', Health: 'healthy'}),
+      JSON.stringify({Name: 'db', State: 'running', Health: ''}),
+    ].join('\n')
+
+    const {ctx, captured} = createCapturedCtx()
+
+    try {
+      await umamiStatusAction({key: 'MY_UMAMI_HOST'}, ctx, makeSpawn(ndjson))
+    } catch (error) {
+      if (!(error instanceof MockProcessExit)) throw error
+    }
+
+    const output = captured.stdout.join('\n')
+    expect(output).toContain('umami')
+    expect(captured.exit).toBeNull()
+  })
+
+  it('exits 1 with a clear message when docker compose ps returns empty output', async () => {
+    process.env.UMAMI_DOMAIN = 'metrics.fro.bot'
+
+    const {ctx, captured} = createCapturedCtx()
+
+    try {
+      await umamiStatusAction({}, ctx, makeSpawn(''))
+    } catch (error) {
+      if (!(error instanceof MockProcessExit)) throw error
+    }
+
+    expect(captured.stderr.join('')).toMatch(/no services|empty/i)
+    expect(captured.exit?.code).toBe(1)
+  })
+
+  it('reports degraded when a service is running but health is unhealthy', async () => {
+    process.env.UMAMI_DOMAIN = 'metrics.fro.bot'
+
+    const ndjson = [
+      JSON.stringify({Name: 'umami', State: 'running', Health: 'unhealthy'}),
+      JSON.stringify({Name: 'db', State: 'running', Health: 'healthy'}),
+    ].join('\n')
+
+    const {ctx, captured} = createCapturedCtx()
+
+    try {
+      await umamiStatusAction({}, ctx, makeSpawn(ndjson))
+    } catch (error) {
+      if (!(error instanceof MockProcessExit)) throw error
+    }
+
+    const output = captured.stdout.join('\n')
+    expect(output).toContain('DEGRADED')
+    expect(captured.exit?.code).toBe(1)
+  })
+
+  it('reports OK when a service is running with health n-a (e.g. caddy has no healthcheck)', async () => {
+    process.env.UMAMI_DOMAIN = 'metrics.fro.bot'
+
+    const ndjson = [
+      JSON.stringify({Name: 'umami', State: 'running', Health: 'healthy'}),
+      JSON.stringify({Name: 'db', State: 'running', Health: 'healthy'}),
+      JSON.stringify({Name: 'caddy', State: 'running', Health: ''}),
+    ].join('\n')
+
+    const {ctx, captured} = createCapturedCtx()
+
+    await umamiStatusAction({}, ctx, makeSpawn(ndjson))
+
+    const output = captured.stdout.join('\n')
+    expect(output).toContain('Status: OK')
+    expect(captured.exit).toBeNull()
+  })
+})

package/src/commands/umami/status.ts

@@ -0,0 +1,267 @@
+import type {goke} from 'goke'
+import type {ActionCtx} from '../../lib/action-ctx'
+import type {StatusSummary} from '../status'
+
+import {z} from 'zod'
+
+import {validateUmamiHost} from './host'
+
+declare const process: {
+  env: Record<string, string | undefined>
+  exitCode?: number
+}
+
+const COMPOSE_PROJECT_DIR = '/opt/umami'
+
+// ─── Types ───────────────────────────────────────────────────────────────────
+
+export interface ComposePsEntry {
+  Name: string
+  State: string
+  Health: string
+}
+
+export type HealthStatus = 'healthy' | 'unhealthy' | 'starting' | 'n-a'
+
+export interface ServiceRow {
+  service: string
+  state: string
+  health: HealthStatus
+}
+
+export interface UmamiStatusResult {
+  ok: boolean
+  services: ServiceRow[]
+  error?: string
+}
+
+export type SpawnFn = (
+  cmd: string[],
+  opts: {env: Record<string, string>; stdout: 'pipe'; stderr: 'pipe'},
+) => {
+  stdout: ReadableStream<Uint8Array>
+  stderr: ReadableStream<Uint8Array>
+  exited: Promise<number>
+}
+
+// ─── Pure helpers ─────────────────────────────────────────────────────────────
+
+export function parseComposePsOutput(stdoutText: string): ComposePsEntry[] {
+  const trimmed = stdoutText.trim()
+  if (trimmed.length === 0) return []
+
+  // Legacy compose may emit a single JSON array; current versions emit NDJSON.
+  if (trimmed.startsWith('[')) {
+    const parsed: unknown = JSON.parse(trimmed)
+    return Array.isArray(parsed) ? (parsed as ComposePsEntry[]) : []
+  }
+
+  // NDJSON: one JSON object per non-empty line.
+  return trimmed
+    .split('\n')
+    .map(line => line.trim())
+    .filter(line => line.length > 0)
+    .map(line => JSON.parse(line) as ComposePsEntry)
+}
+
+function normalizeHealth(raw: string): HealthStatus {
+  if (raw === 'healthy' || raw === 'unhealthy' || raw === 'starting') {
+    return raw
+  }
+
+  return 'n-a'
+}
+
+export function parseComposePs(entries: ComposePsEntry[]): ServiceRow[] {
+  return entries.map(entry => ({
+    service: entry.Name,
+    state: entry.State,
+    health: normalizeHealth(entry.Health),
+  }))
+}
+
+export function isAllRunning(rows: ServiceRow[]): boolean {
+  return rows.every(row => row.state === 'running' && (row.health === 'healthy' || row.health === 'n-a'))
+}
+
+// ─── SSH-backed status fetch ──────────────────────────────────────────────────
+
+function defaultSpawn(
+  cmd: string[],
+  opts: {env: Record<string, string>; stdout: 'pipe'; stderr: 'pipe'},
+): ReturnType<SpawnFn> {
+  return Bun.spawn(cmd, opts) as ReturnType<SpawnFn>
+}
+
+export async function getUmamiComposeStatus(host: string, spawn: SpawnFn = defaultSpawn): Promise<UmamiStatusResult> {
+  validateUmamiHost(host)
+
+  const sshCmd = [
+    'ssh',
+    '-o',
+    'BatchMode=yes',
+    '-o',
+    'StrictHostKeyChecking=yes',
+    `root@${host}`,
+    `docker compose --project-directory ${COMPOSE_PROJECT_DIR} ps --format json`,
+  ]
+
+  const env: Record<string, string> = {
+    PATH: process.env.PATH ?? '/usr/bin:/bin',
+    HOME: process.env.HOME ?? '/tmp',
+    ...(process.env.SSH_AUTH_SOCK ? {SSH_AUTH_SOCK: process.env.SSH_AUTH_SOCK} : {}),
+  }
+
+  const child = spawn(sshCmd, {env, stdout: 'pipe', stderr: 'pipe'})
+
+  const [stdoutText, stderrText, exitCode] = await Promise.all([
+    new Response(child.stdout).text(),
+    new Response(child.stderr).text(),
+    child.exited,
+  ])
+
+  if (exitCode !== 0) {
+    return {
+      ok: false,
+      services: [],
+      error: `SSH command failed (exit ${exitCode}): ${stderrText.trim() || 'unknown error'}`,
+    }
+  }
+
+  let entries: ComposePsEntry[]
+
+  try {
+    entries = parseComposePsOutput(stdoutText)
+  } catch {
+    return {ok: false, services: [], error: `Failed to parse docker compose ps output: ${stdoutText.slice(0, 200)}`}
+  }
+
+  const services = parseComposePs(entries)
+  const ok = isAllRunning(services)
+
+  return {ok, services}
+}
+
+// ─── Unified status aggregator export ────────────────────────────────────────
+
+export async function getUmamiStatusSummary(host: string, spawn?: SpawnFn): Promise<StatusSummary> {
+  let result: UmamiStatusResult
+
+  try {
+    result = await getUmamiComposeStatus(host, spawn)
+  } catch (error) {
+    const errorMsg = error instanceof Error ? error.message : String(error)
+    return {
+      app: 'umami',
+      http: `ERROR: ${errorMsg}`,
+      lastDeploy: '—',
+      version: '—',
+      contentHash: '—',
+      usageStats: '—',
+    }
+  }
+
+  // Three-way split: no services → ERROR, services present but degraded → DEGRADED, all healthy → OK
+  if (result.services.length === 0) {
+    const errorMsg = result.error ?? 'No services reported'
+    return {
+      app: 'umami',
+      http: `ERROR: ${errorMsg}`,
+      lastDeploy: '—',
+      version: '—',
+      contentHash: '—',
+      usageStats: '—',
+    }
+  }
+
+  const rows = result.services.map(s => `${s.service}:${s.state}/${s.health}`).join(', ')
+
+  if (!result.ok) {
+    return {
+      app: 'umami',
+      http: `DEGRADED: ${rows}`,
+      lastDeploy: '—',
+      version: '—',
+      contentHash: '—',
+      usageStats: '—',
+    }
+  }
+
+  return {
+    app: 'umami',
+    http: `OK: ${rows}`,
+    lastDeploy: '—',
+    version: '—',
+    contentHash: '—',
+    usageStats: '—',
+  }
+}
+
+// ─── Action (exported for direct testing) ────────────────────────────────────
+
+export async function umamiStatusAction(
+  options: {key?: string | undefined},
+  ctx: ActionCtx,
+  spawn?: SpawnFn,
+): Promise<void> {
+  const hostEnvKey = options.key ?? 'UMAMI_DOMAIN'
+  const host = process.env[hostEnvKey]
+
+  if (!host) {
+    ctx.console.error('Umami host not set. Export UMAMI_DOMAIN or pass --key <env-name> pointing to a set variable.')
+    ctx.process.exit(1)
+    return
+  }
+
+  ctx.console.log('Umami status')
+  ctx.console.log('')
+
+  let result: UmamiStatusResult
+
+  try {
+    result = await getUmamiComposeStatus(host, spawn)
+  } catch (error) {
+    ctx.console.error(`Error: ${error instanceof Error ? error.message : String(error)}`)
+    ctx.process.exit(1)
+    return
+  }
+
+  if (result.services.length === 0) {
+    ctx.console.error(`Error: No services reported by docker compose ps`)
+    ctx.process.exit(1)
+    return
+  }
+
+  ctx.console.log('Service          State      Health')
+  ctx.console.log('─────────────────────────────────────')
+
+  for (const row of result.services) {
+    const svc = row.service.padEnd(16)
+    const state = row.state.padEnd(10)
+    ctx.console.log(`${svc} ${state} ${row.health}`)
+  }
+
+  ctx.console.log('')
+
+  if (result.ok) {
+    ctx.console.log('Status: OK')
+  } else {
+    ctx.console.log('Status: DEGRADED (one or more services not running)')
+    ctx.process.exit(1)
+  }
+}
+
+// ─── Command registration ─────────────────────────────────────────────────────
+
+export function registerUmamiStatus(cli: ReturnType<typeof goke>): void {
+  cli
+    .command('umami status', 'Show operational health of the Umami analytics deployment via docker compose ps.')
+    .option(
+      '--key [key]',
+      z
+        .string()
+        .optional()
+        .describe('Environment variable name holding the SSH host. Falls back to UMAMI_DOMAIN when omitted.'),
+    )
+    .action((options, ctx) => umamiStatusAction(options, ctx))
+}