first commit

plugins/library-navigator/skills/sp-health-check/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: sp-health-check
+description: Server-tier /health, /ready, /live endpoints with dependency checks — HealthChecker, ResponseBuilder, HttpCheck, TcpCheck with injectable deps.
+---
+
+# Architecture
+
+| Component | Responsibility |
+|---|---|
+| `HealthChecker` | Registry, runner, and aggregator for dependency checks; owns `EventBus` for lifecycle events |
+| `createHttpCheck` | Returns `CheckFn` that probes an HTTP endpoint with injectable `fetchImpl` and configurable status whitelist |
+| `createTcpCheck` | Returns `CheckFn` that opens a TCP socket against `host:port` with injectable `TcpConnectFn` |
+| `ResponseBuilder` | Adapts `HealthChecker` into HTTP-shaped responses for Hono / Express / raw fetch |
+| `HEALTH_CHECK_CODES` + `HealthCheckError` | Structured errors with stable `HEALTH_CHECK.*` codes |
+| `aggregateStatusCounter` / `checkDurationHistogram` / `checkRunCounter` | OTel self-telemetry counters and histograms |
+
+## File Structure
+
+```
+packages/observability/monitor/health-check/src/
+  health-checker/       HealthChecker class and helpers
+  http-check/           createHttpCheck with injectable fetch
+  tcp-check/            createTcpCheck with injectable socket
+  response-builder/     ResponseBuilder mapping statuses to HTTP codes
+  error-codes/          HEALTH_CHECK_CODES and HealthCheckError
+  telemetry/            OTel meter registration
+  types/                TypeScript interfaces (CheckFn, CheckResult, HealthResponse, etc.)
+```
+
+## Sibling packages
+
+- `@suaveplan/events` — typed EventBus for health status change notifications
+- `@suaveplan/logger` — structured logging integration
+- `@suaveplan/opentelemetry` — OTel SDK setup helpers
+- `@suaveplan/error` — structured error registry via `defineCodes`
+- `@suaveplan/types` — shared TypeScript primitives
+- `@suaveplan/testing` — unit test infrastructure
+
+## Patterns
+
+### Quick Start
+
+```ts
+import { HealthChecker, ResponseBuilder, createHttpCheck, createTcpCheck } from "@suaveplan/health-check";
+
+const checker = new HealthChecker({ name: "api", version: "1.0.0" });
+checker.addCheck({
+  name: "upstream",
+  check: createHttpCheck({ url: "https://up.example.com/health" }),
+});
+checker.addCheck({
+  name: "postgres",
+  check: createTcpCheck({ host: "db.internal", port: 5432 }),
+});
+
+const builder = new ResponseBuilder(checker);
+const { statusCode, body } = await builder.health();
+```
+
+### Custom check function
+
+```ts
+checker.addCheck({
+  name: "custom",
+  check: async () => ({ status: "healthy", responseTimeMs: 12 }),
+});
+```
+
+### Lifecycle events
+
+```ts
+checker.events.on("statusChanged", ({ checkName, from, to }) => {
+  console.log(`${checkName}: ${from} → ${to}`);
+});
+```
+
+## Constraints
+
+- Node.js >=20 required (TCP socket APIs)
+- Every `CheckFn` receives injectable `{ clock?, timers?, logger?, fetch?, signal? }`
+- `HealthChecker` caches results with configurable TTL to avoid thundering herd
+- ResponseBuilder maps aggregate status: `healthy` → 200, `degraded` → 200, `unhealthy` → 503
+
+## Checklist
+
+- [ ] Verify `HealthChecker` supports HTTP, TCP, and custom check types
+- [ ] Confirm `HEALTH_CHECK_CODES` registered via `defineCodes("HEALTH_CHECK", [...])`
+- [ ] Check subpath exports in `package.json` align with `src/` modules
+- [ ] Run `bunx turbo lint typecheck test build --filter=@suaveplan/health-check`
+- [ ] Confirm OTel counters increment correctly during check runs