stacks-health

name	stacks-health
description	Use when implementing health checks in a Stacks application — service monitoring, health endpoints, or diagnostic checks. Covers @stacksjs/health (currently WIP — Oh Dear integration planned).
license	MIT
compatibility	Bun >= 1.3.0, TypeScript
allowed-tools	Read Edit Write Bash Grep Glob

Stacks Health

Key Paths

• Core package: storage/framework/core/health/src/
• Drivers: storage/framework/core/health/src/drivers/
• Notifications: storage/framework/core/health/src/notifications/
• Package: @stacksjs/health

Source Files

health/src/
├── index.ts              # Re-exports drivers and notifications
├── drivers/
│   ├── index.ts          # Driver exports
│   └── ohdear.ts         # Oh Dear health check driver (WIP)
└── notifications/
    └── index.ts          # Health notifications (WIP)

Current Status

This package is WIP. Current exports are placeholder markers:

export const ohdearWip = 1              // Oh Dear driver placeholder
export const healthNotificationsWip = 1  // Notifications placeholder

Built-in Health Endpoint

The health check functionality currently lives in the router, not this package:

GET /health

Returns:

{
  "status": "ok",
  "uptime": 12345,
  "memory": { "rss": 1234567, "heapUsed": 987654 },
  "pid": 1234,
  "bunVersion": "1.3.0"
}

This endpoint is registered via route.health() in the router.

CLI Commands

buddy doctor              # Comprehensive system diagnostics

Planned Features

• Oh Dear integration for external health monitoring
• Health check notifications (email, Slack, etc.)
• Custom health check drivers
• Database connectivity checks
• External service status verification

Gotchas

• Package is WIP — only placeholder exports exist
• Health endpoint is in the router — GET /health works via route.health(), not this package
• buddy doctor — system diagnostics are in the buddy CLI, not this health package
• Oh Dear driver planned — integration with ohdear.app for external monitoring