@zyno-io/dk-server-foundation 26.216.430

package/docs/content/devconsole.md

@@ -0,0 +1,123 @@
+# DevConsole
+
+A built-in web dashboard for development-time monitoring and debugging. Automatically enabled when `APP_ENV !== 'production'` and accessible at `http://localhost:{PORT}/_devconsole/`.
+
+DevConsole is zero-config, localhost-only, and requires no additional setup beyond running your app in development mode.
+
+## Screenshots
+
+### Dashboard
+![DevConsole Dashboard](/images/devconsole/01-dashboard.png)
+
+### Routes
+![DevConsole Routes](/images/devconsole/02-routes.png)
+
+### OpenAPI Schema
+![DevConsole OpenAPI](/images/devconsole/03-openapi.png)
+
+### HTTP Requests
+![DevConsole Requests](/images/devconsole/04-requests.png)
+
+### SRPC
+![DevConsole SRPC](/images/devconsole/05-srpc.png)
+
+### Database
+![DevConsole Database](/images/devconsole/06-database.png)
+
+### Health Checks
+![DevConsole Health](/images/devconsole/07-health.png)
+
+### Mutex Monitor
+![DevConsole Mutex](/images/devconsole/08-mutex.png)
+
+### Interactive REPL
+![DevConsole REPL](/images/devconsole/09-repl.png)
+
+### Workers
+![DevConsole Workers](/images/devconsole/10-workers.png)
+
+## Views
+
+### Dashboard
+
+App overview showing name, version, environment, uptime, and real-time statistics (HTTP request count, SRPC connections/messages). Also displays process info: PID, Node version, platform, CPU usage, and memory consumption.
+
+### Routes
+
+Lists all registered HTTP routes with their methods, paths, controller class, and handler method. Internal `/_devconsole` routes are excluded.
+
+### OpenAPI
+
+Displays the OpenAPI schema generated from your HTTP routes. The schema is generated on-demand from route metadata via `deepkit-openapi-core`.
+
+### Requests
+
+HTTP request inspector capturing the last 500 requests. Shows timestamp, method, URL, status code, duration, and remote address. Expanding a request reveals full request/response headers and bodies (up to 32KB), plus error details with stack traces for failed requests. New requests appear in real time.
+
+### SRPC
+
+SRPC connection monitor showing active connections (client ID, stream ID, app version, address, uptime, ping, message count) and recent disconnections. Includes a message-level inspector (last 500 messages) showing type, direction, request ID, reply status, and errors. Messages can be filtered by stream ID.
+
+### Database
+
+Entity browser listing all registered ORM entities with table names and columns. Includes a SQL query editor — `SELECT` queries return result rows, while `INSERT`/`UPDATE`/`DELETE` return affected row counts. Execute with Ctrl+Enter.
+
+### Health
+
+Displays results from all registered health checks with status (ok/error) and error messages.
+
+### Mutex
+
+Redis mutex monitor showing active mutexes (key, status, timing) and a history of the last 200 completed/failed acquisitions with wait and hold duration metrics.
+
+### REPL
+
+Interactive JavaScript REPL running in the server's context. Access DI-registered classes via `$` and instances via `$$`. Supports Tab-completion, command history (arrow keys), and multiline input (Shift+Enter). Console output (`log`, `warn`, `error`) is captured and displayed.
+
+### Environment
+
+Displays application configuration from the config class. Keys containing `SECRET`, `PASSWORD`, `DSN`, `TOKEN`, or `KEY` are masked.
+
+### Workers
+
+BullMQ job inspector showing queue statistics (active, waiting, delayed, completed, failed counts), live jobs, and job history (last 200 from the `_jobs` table).
+
+## Architecture
+
+### Transport
+
+DevConsole uses SRPC over WebSocket (`/_devconsole/ws`) for bidirectional communication. The protocol is defined in `resources/proto/devconsole.proto` and uses Protocol Buffers for encoding.
+
+Real-time events (new HTTP requests, SRPC messages, mutex state changes, worker jobs) are pushed from server to client without polling.
+
+### Security
+
+Access is restricted to localhost connections only. The `DevConsoleLocalhostMiddleware` checks that the request originates from `127.0.0.1` or `::1` using the socket's `remoteAddress` (not proxy headers). SRPC authentication is bypassed for DevConsole connections.
+
+### How It Works
+
+DevConsole initializes via `initDevConsole()` in `src/devconsole/patches.ts`, which monkey-patches core framework components to intercept events:
+
+- **HTTP Kernel** — captures request/response data for the Requests view
+- **HTTP Workflow** — captures controller errors
+- **SRPC Client & Server** — observes messages and connection lifecycle
+- **Worker Recorder** — listens to BullMQ job events
+- **Mutex (`withMutex`)** — tracks mutex acquisitions and releases
+
+Captured data is stored in ring buffers (`DevConsoleStore`) for bounded memory usage.
+
+### Frontend
+
+The frontend is a Vue 3 SPA built with Vite. Source lives in `devconsole/` and builds to `dist/devconsole/`. The built assets are served by `DevConsoleController` at `/_devconsole/`.
+
+In development, the frontend can be run standalone with `cd devconsole && npm run dev`, which proxies API and WebSocket requests to `localhost:3000`.
+
+## Demo App
+
+A demo application is included to showcase all DevConsole features:
+
+```bash
+yarn demoapp
+```
+
+This starts a server at `http://localhost:3000` with auto-generated HTTP traffic, SRPC client/server chatter, worker jobs, and mutex contention. Open `http://localhost:3000/_devconsole/` to see it all in action.

package/docs/content/getting-started.md

@@ -0,0 +1,154 @@
+# Getting Started
+
+## Installation
+
+```bash
+npm install @zyno-io/dk-server-foundation
+# or
+yarn add @zyno-io/dk-server-foundation
+```
+
+### TypeScript Configuration
+
+Your `tsconfig.json` must enable experimental decorators and Deepkit reflection:
+
+```json
+{
+    "compilerOptions": {
+        "experimentalDecorators": true
+    },
+    "reflection": true
+}
+```
+
+## Creating an Application
+
+Use `createApp()` to set up a Deepkit application with opinionated defaults.
+
+```typescript
+import { createApp, BaseAppConfig, createMySQLDatabase } from '@zyno-io/dk-server-foundation';
+
+// 1. Define your config
+class AppConfig extends BaseAppConfig {
+    STRIPE_KEY_SECRET!: string;
+}
+
+// 2. Define your database
+class AppDB extends createMySQLDatabase({}, [UserEntity, PostEntity]) {}
+
+// 3. Create and run
+const app = createApp({
+    config: AppConfig,
+    db: AppDB,
+    enableWorker: true,
+    cors: config => ({
+        hosts: ['https://myapp.com'],
+        credentials: true
+    }),
+    controllers: [UserController, PostController],
+    providers: [UserService, PostService]
+});
+
+app.run();
+```
+
+### What `createApp()` Sets Up
+
+- HTTP server on port 3000 (configurable via `PORT`)
+- Custom HTTP kernel with request logging
+- Health check endpoint at `GET /healthz`
+- Multipart form parsing (JSON key: `_payload`)
+- REPL and provider invoke CLI commands
+- [DevConsole](./devconsole.md) at `/_devconsole/` with request inspector, REPL, database browser, and more (development only)
+- Sentry integration (if `SENTRY_DSN` is set)
+- Graceful shutdown with 30-second timeout
+
+## `createApp()` Options
+
+```typescript
+interface CreateAppOptions<C extends BaseAppConfig> extends RootModuleDefinition {
+    config: ClassType<C>;
+    defaultConfig?: Partial<C>;
+    db?: ClassType<BaseDatabase>;
+    frameworkConfig?: Partial<FrameworkConfig>;
+    cors?: (config: C) => HttpCorsOptions | HttpCorsOptions[];
+    enableWorker?: boolean;
+    enableDkRpc?: boolean;
+}
+```
+
+| Option            | Required | Description                                                                                               |
+| ----------------- | -------- | --------------------------------------------------------------------------------------------------------- |
+| `config`          | Yes      | Config class extending `BaseAppConfig`. Properties are loaded from environment variables.                 |
+| `defaultConfig`   | No       | Default values for config properties.                                                                     |
+| `db`              | No       | Database class created via `createMySQLDatabase()`. Registers health check and enables entity management. |
+| `frameworkConfig` | No       | Override Deepkit framework settings (debug mode, etc.).                                                   |
+| `cors`            | No       | Factory function returning CORS options. Receives the resolved config instance.                           |
+| `enableWorker`    | No       | Enable BullMQ worker system. Registers job runner with leader-elected recorder and CLI commands.          |
+| `enableDkRpc`     | No       | Enable Deepkit's built-in RPC module.                                                                     |
+
+Standard Deepkit `RootModuleDefinition` fields are also accepted: `controllers`, `providers`, `listeners`, `imports`, `exports`, `workflows`, `middlewares`.
+
+## AutoStart Decorator
+
+Services decorated with `@AutoStart()` are instantiated at application startup, before dependency injection requests. Use this for services that need to establish connections or start background processes.
+
+```typescript
+import { AutoStart } from '@zyno-io/dk-server-foundation';
+
+@AutoStart()
+class WebSocketManager {
+    constructor() {
+        // Automatically called at startup
+        this.connect();
+    }
+}
+```
+
+## Dependency Resolution
+
+Use `resolve()` (or its alias `r()`) to access providers outside of constructor injection:
+
+```typescript
+import { r, resolve, getApp, getAppConfig } from '@zyno-io/dk-server-foundation';
+
+// Resolve a provider
+const db = r(MyDatabase);
+const logger = resolve(ExtendedLogger);
+
+// Access the app or config
+const app = getApp();
+const config = getAppConfig();
+```
+
+### `resolveDeep(type, fromModule?)`
+
+Recursively searches through module imports to find a provider. Returns `undefined` if not found.
+
+```typescript
+import { resolveDeep } from '@zyno-io/dk-server-foundation';
+
+const service = resolveDeep(MyService); // searches all modules
+```
+
+## Environment Detection
+
+```typescript
+import { isDevelopment, isTest } from '@zyno-io/dk-server-foundation';
+
+if (isDevelopment) {
+    // APP_ENV and NODE_ENV are unset or 'development'
+}
+
+if (isTest) {
+    // Running inside Jest or APP_ENV === 'test'
+}
+```
+
+## Timezone
+
+The library enforces UTC at startup. If `TZ` is not set to `UTC`, the process will throw an error. Set the environment variable before starting:
+
+```bash
+TZ=UTC node app.js
+```

package/docs/content/guides/test-migration-guide.md

@@ -0,0 +1,351 @@
+# Migrating from Jest to node:test (dk-server-foundation)
+
+This guide documents how to migrate a project that uses `@zyno-io/dk-server-foundation` from Jest to Node.js's built-in `node:test` runner. It is written as a reference for Claude and other AI assistants performing this migration.
+
+## Why node:test?
+
+Since projects already build to CJS via `tsc` (which runs the Deepkit type compiler), testing against the built output eliminates test-time compilation entirely — Deepkit reflection is already compiled in.
+
+Benefits:
+
+- Tests run against the same compiled output as production
+- Faster test startup (no transform pipeline)
+- Zero-config Deepkit reflection (already compiled by `tsc`)
+
+## Step-by-step migration
+
+### 1. Create `tsconfig.test.json`
+
+Extend the base `tsconfig.json` to also compile test files:
+
+```json
+{
+    "extends": "./tsconfig.json",
+    "compilerOptions": {
+        "declaration": false,
+        "declarationMap": false
+    },
+    "include": ["src/**/*", "tests/**/*", "types.d.ts"]
+}
+```
+
+This compiles `tests/` into `dist/tests/` alongside `dist/src/`. Relative imports like `../../src/foo` naturally resolve to `dist/src/foo` in the output.
+
+### 2. Create `globalSetup.ts`
+
+Create `tests/shared/globalSetup.ts` with `setup` and `teardown` exports:
+
+```typescript
+import { TestingHelpers } from '@zyno-io/dk-server-foundation';
+
+export async function setup() {
+    TestingHelpers.setDefaultDatabaseConfig({
+        MYSQL_HOST: 'localhost',
+        MYSQL_PORT: 3306,
+        MYSQL_USER: 'root',
+        MYSQL_PASSWORD_SECRET: 'secret'
+    });
+
+    await TestingHelpers.cleanupTestDatabases('myapp_test');
+}
+
+export async function teardown() {
+    await TestingHelpers.cleanupTestDatabases('myapp_test');
+}
+```
+
+The `dksf-test` runner will automatically load `dist/tests/shared/globalSetup.js` if it exists, calling `setup()` before tests and `teardown()` after.
+
+### 3. Update `package.json` scripts
+
+```json
+{
+    "scripts": {
+        "test": "tsc -p tsconfig.test.json && dksf-test",
+        "test:debug": "tsc -p tsconfig.test.json && node --inspect=9201 node_modules/.bin/dksf-test"
+    }
+}
+```
+
+`dksf-test` sets `APP_ENV=test` and `TZ=UTC` automatically, finds all `*.spec.js` files in `dist/tests/`, and runs them with `node --test`. You can pass specific files and node flags:
+
+```bash
+# Run a single test file (source path is mapped to dist automatically)
+yarn test tests/my-feature.spec.ts
+
+# Run all tests in a directory
+yarn test tests/integration/
+
+# Pass node flags
+yarn test --test-name-pattern="my test"
+```
+
+Remove Jest dependencies and configuration files.
+
+### 4. Migrate test imports
+
+Add explicit imports at the top of each test file:
+
+```typescript
+import { describe, it, before, after, beforeEach, afterEach, mock } from 'node:test';
+import assert from 'node:assert/strict';
+```
+
+Rename any `beforeAll`/`afterAll` calls to `before`/`after`.
+
+### 5. Migrate assertions
+
+#### Simple replacements
+
+| Jest                                        | node:test                                         |
+| ------------------------------------------- | ------------------------------------------------- |
+| `expect(x).toBe(y)`                         | `assert.strictEqual(x, y)`                        |
+| `expect(x).toEqual(y)`                      | `assert.deepStrictEqual(x, y)`                    |
+| `expect(x).toBeDefined()`                   | `assert.notStrictEqual(x, undefined)`             |
+| `expect(x).toBeUndefined()`                 | `assert.strictEqual(x, undefined)`                |
+| `expect(x).toBeNull()`                      | `assert.strictEqual(x, null)`                     |
+| `expect(x).toBeTruthy()`                    | `assert.ok(x)`                                    |
+| `expect(x).toBeFalsy()`                     | `assert.ok(!x)`                                   |
+| `expect(x).toBeInstanceOf(Y)`               | `assert.ok(x instanceof Y)`                       |
+| `expect(x).toHaveLength(n)`                 | `assert.strictEqual(x.length, n)`                 |
+| `expect(x).toContain(y)`                    | `assert.ok(x.includes(y))`                        |
+| `expect(x).toMatch(/re/)`                   | `assert.match(x, /re/)`                           |
+| `expect(x).toBeGreaterThan(n)`              | `assert.ok(x > n)`                                |
+| `expect(x).toBeGreaterThanOrEqual(n)`       | `assert.ok(x >= n)`                               |
+| `expect(x).toBeLessThan(n)`                 | `assert.ok(x < n)`                                |
+| `expect(x).toHaveProperty(k)`               | `assert.ok(k in x)`                               |
+| `expect(x).not.toBe(y)`                     | `assert.notStrictEqual(x, y)`                     |
+| `expect(x).not.toEqual(y)`                  | `assert.notDeepStrictEqual(x, y)`                 |
+| `expect(() => fn()).toThrow(msg)`           | `assert.throws(() => fn(), { message: msg })`     |
+| `expect(() => fn()).toThrow(ErrClass)`      | `assert.throws(() => fn(), ErrClass)`             |
+| `expect(() => fn()).toThrow(/re/)`          | `assert.throws(() => fn(), /re/)`                 |
+| `expect(() => fn()).not.toThrow()`          | `assert.doesNotThrow(() => fn())`                 |
+| `expect(promise).rejects.toThrow(msg)`      | `await assert.rejects(promise, { message: msg })` |
+| `expect(promise).rejects.toThrow(/re/)`     | `await assert.rejects(promise, /re/)`             |
+| `expect(promise).rejects.toThrow(ErrClass)` | `await assert.rejects(promise, ErrClass)`         |
+
+#### `toMatchObject` — use `matchesObject` from dk-server-foundation
+
+```typescript
+import { matchesObject } from '@zyno-io/dk-server-foundation/testing/expect';
+
+// Before
+expect(result).toMatchObject({ name: 'Fred', age: 30 });
+
+// After
+matchesObject(result, { name: 'Fred', age: 30 });
+```
+
+#### Asymmetric matchers — use helpers from dk-server-foundation
+
+```typescript
+import { matchesObject, anyOf, stringContaining, arrayContaining, anything, objectContaining } from '@zyno-io/dk-server-foundation/testing/expect';
+
+// Before
+expect(result).toMatchObject({ id: expect.any(Number), name: expect.stringContaining('Fred') });
+
+// After
+matchesObject(result, { id: anyOf(Number), name: stringContaining('Fred') });
+```
+
+Available matchers:
+| Jest | dk-server-foundation |
+|---|---|
+| `expect.any(Type)` | `anyOf(Type)` |
+| `expect.anything()` | `anything()` |
+| `expect.stringContaining(s)` | `stringContaining(s)` |
+| `expect.arrayContaining(arr)` | `arrayContaining(arr)` |
+| `expect.objectContaining(obj)` | `objectContaining(obj)` |
+
+#### Mock assertions — use `assertCalledWith`
+
+```typescript
+import { assertCalledWith, anyOf } from '@zyno-io/dk-server-foundation/testing/expect';
+
+// Before
+expect(mockFn).toHaveBeenCalledWith('arg1', expect.any(Number));
+
+// After
+assertCalledWith(mockFn, 'arg1', anyOf(Number));
+```
+
+Other mock assertion conversions:
+
+| Jest                                  | node:test                                    |
+| ------------------------------------- | -------------------------------------------- |
+| `expect(fn).toHaveBeenCalledTimes(n)` | `assert.strictEqual(fn.mock.callCount(), n)` |
+| `expect(fn).toHaveBeenCalled()`       | `assert.ok(fn.mock.callCount() > 0)`         |
+| `expect(fn).not.toHaveBeenCalled()`   | `assert.strictEqual(fn.mock.callCount(), 0)` |
+| `fn.mock.calls[0][1]`                 | `fn.mock.calls[0].arguments[1]`              |
+| `fn.mockClear()`                      | `fn.mock.resetCalls()`                       |
+
+### 6. Migrate mock APIs
+
+| Jest                                           | node:test                                 |
+| ---------------------------------------------- | ----------------------------------------- |
+| `jest.fn()`                                    | `mock.fn()`                               |
+| `jest.fn(() => value)`                         | `mock.fn(() => value)`                    |
+| `jest.spyOn(obj, method)`                      | `mock.method(obj, method)`                |
+| `jest.spyOn(obj, method).mockReturnValue(x)`   | `mock.method(obj, method, () => x)`       |
+| `jest.spyOn(obj, method).mockResolvedValue(x)` | `mock.method(obj, method, async () => x)` |
+| `jest.clearAllMocks()`                         | Per-mock `fn.mock.resetCalls()`           |
+| `jest.restoreAllMocks()`                       | `mock.restoreAll()`                       |
+| `jest.useFakeTimers()`                         | `mock.timers.enable()`                    |
+| `jest.advanceTimersByTime(n)`                  | `mock.timers.tick(n)`                     |
+| `jest.useRealTimers()`                         | `mock.timers.reset()`                     |
+| `jest.setTimeout(n)`                           | `--test-timeout=N` flag in test runner    |
+
+#### `mockReturnValue` / `mockImplementation` on existing mocks
+
+node:test does not have `mockReturnValue()` or `mockImplementation()` on mock instances. Instead, pass the implementation when creating the mock:
+
+```typescript
+// Jest
+const fn = jest.fn();
+fn.mockReturnValue(42);
+fn.mockImplementation(x => x * 2);
+
+// node:test
+const fn = mock.fn(() => 42);
+// To change implementation later, create a new mock or use a wrapper:
+let impl = (x: number) => x * 2;
+const fn = mock.fn((x: number) => impl(x));
+impl = (x: number) => x * 3; // change behavior
+```
+
+#### `mockReturnValueOnce` — no direct equivalent
+
+Use a counter or array of return values:
+
+```typescript
+// Jest
+fn.mockReturnValueOnce(1).mockReturnValueOnce(2).mockReturnValue(0);
+
+// node:test
+const returns = [1, 2];
+const fn = mock.fn(() => returns.shift() ?? 0);
+```
+
+### 7. Migrate module mocking
+
+Since tests run against CJS output, use `require.cache` manipulation with `TestingHelpers.resetSrcModuleCache()`:
+
+```typescript
+// Before (Jest)
+jest.doMock('../../src/app/resolver', () => ({
+    getAppConfig: () => mockConfig
+}));
+const { MyModule } = await import('../../src/my-module');
+
+// After (node:test with CJS)
+import { TestingHelpers } from '@zyno-io/dk-server-foundation';
+
+TestingHelpers.resetSrcModuleCache();
+const resolver = require('../../src/app/resolver');
+resolver.getAppConfig = () => mockConfig;
+const { MyModule } = require('../../src/my-module');
+```
+
+This works because CJS `import { x } from 'y'` compiles to `const y_1 = require('y')`, preserving a reference to the module exports object. Patching `resolver.getAppConfig` is visible to all subsequently-required modules.
+
+### 8. Migrate `it.skip`, `it.only`, `it.each`
+
+**`it.skip` / `describe.skip`** — same syntax, works identically:
+
+```typescript
+it.skip('not yet implemented', () => { ... });
+describe.skip('disabled suite', () => { ... });
+```
+
+**`it.only` / `describe.only`** — same syntax, but only affects the current file. To filter tests across files, use `--test-name-pattern`:
+
+```bash
+node --test --test-name-pattern="my test name" dist/tests/**/*.spec.js
+```
+
+**`it.each` / `describe.each`** — no built-in equivalent. Use a loop:
+
+```typescript
+// Jest
+it.each([
+    [1, 2, 3],
+    [4, 5, 9]
+])('adds %i + %i = %i', (a, b, expected) => {
+    expect(a + b).toBe(expected);
+});
+
+// node:test
+for (const [a, b, expected] of [
+    [1, 2, 3],
+    [4, 5, 9]
+]) {
+    it(`adds ${a} + ${b} = ${expected}`, () => {
+        assert.strictEqual(a + b, expected);
+    });
+}
+```
+
+### 9. Migrate test timeouts
+
+| Jest                     | node:test                             |
+| ------------------------ | ------------------------------------- |
+| `it('name', fn, 30_000)` | `it('name', { timeout: 30_000 }, fn)` |
+| `beforeAll(fn, 10_000)`  | `before(fn, { timeout: 10_000 })`     |
+
+### 10. Environment detection
+
+The `isTest` constant in dk-server-foundation checks `process.env.APP_ENV === 'test'`. The config loader auto-detects `node --test` and sets `APP_ENV=test` if it wasn't already set, so test-time behaviors (e.g., skipping worker job queueing) work automatically.
+
+### 11. Clean up Redis connections
+
+If your tests use Redis-backed features (mutex, cache, leader election, mesh), call `disconnectAllRedis()` in your top-level `after()` hook to properly close memoized connections. Without this, `node:test` child processes will hang waiting for the event loop to drain.
+
+```typescript
+import { after } from 'node:test';
+import { disconnectAllRedis } from '@zyno-io/dk-server-foundation';
+
+after(async () => {
+    await tf.stop();
+    await disconnectAllRedis();
+});
+```
+
+### 12. Remove old config files
+
+Delete these files if they exist:
+
+- `jest.config.js` / `jest.config.ts`
+
+## Troubleshooting
+
+### `APP_ENV must be specified in the environment`
+
+Set `APP_ENV=test` in your test runner script (see step 2). The config loader auto-detects `node --test`, but if you use a custom runner that spawns node separately, set the env var explicitly.
+
+### Tests hang or time out
+
+`node:test` runs test files sequentially by default. If your `before`/`after` hooks don't complete (e.g., database connection not closing), the entire suite will hang. Ensure all connections are properly closed in `after()` hooks. See step 10 for Redis cleanup.
+
+### `beforeAll` / `afterAll` is not defined
+
+Replace with `before`/`after` from `node:test`:
+
+```typescript
+import { before, after } from 'node:test';
+```
+
+### Source maps not working
+
+Ensure `--enable-source-maps` is passed to `node` in your test runner. The `tsconfig.json` must have `"sourceMap": true`.
+
+### Mock function call structure differences
+
+In `node:test`, mock call arguments are accessed via `.arguments` property, not as a flat array:
+
+```typescript
+// Jest
+fn.mock.calls[0][1]; // second argument of first call
+
+// node:test
+fn.mock.calls[0].arguments[1]; // second argument of first call
+```

package/docs/content/health.md

@@ -0,0 +1,54 @@
+# Health Checks
+
+Built-in health check system with an extensible service and HTTP endpoint.
+
+## Endpoint
+
+```
+GET /healthz
+```
+
+Returns:
+
+```json
+{ "version": "1.2.3" }
+```
+
+The version is read from `package.json`. Returns `"unknown"` if not available.
+
+If any registered health check fails, the endpoint returns an HTTP 500 error.
+
+## Registering Health Checks
+
+```typescript
+import { HealthcheckService } from '@zyno-io/dk-server-foundation';
+
+class MyService {
+    constructor(private hcSvc: HealthcheckService) {
+        hcSvc.register('Database', async () => {
+            // Throw to indicate unhealthy
+            await db.rawQuery(sql`SELECT 1`);
+        });
+    }
+}
+```
+
+### Database Health Check
+
+When a database class is passed to `createApp()`, a database health check is automatically registered. It verifies the database connection is alive.
+
+## `HealthcheckService`
+
+| Method                                    | Description                                                                                 |
+| ----------------------------------------- | ------------------------------------------------------------------------------------------- |
+| `register(name, fn: () => Promise<void>)` | Register a named health check function. Throw to indicate failure.                          |
+| `check()`                                 | Run all registered health checks. Throws on first failure.                                  |
+| `checkIndividual()`                       | Run all checks and return per-check results: `{ name, status: 'ok' \| 'error', error? }[]`. |
+
+## Health Module
+
+The `HealthModule` is automatically included by `createApp()`. It provides:
+
+- `HealthcheckService` as a DI provider
+- `HealthcheckController` at `/healthz`
+- `MetricsController` at `/metrics` (if Prometheus exporter is enabled)