# @lilith/service-lib

Shared platform utilities for Lilith services. This package provides the common Fastify factory, middleware, auth helpers, logging, tracing, configuration loaders, and supporting types consumed by the service fleet.

## Supported entrypoints
- `index.js`: primary re-export surface for common helpers.
- `create-fastify-server.cjs`: baseline Fastify factory used by lightweight services.
- `middleware/common.cjs`: common web middleware (CORS, compression, helmet).
- `auth-middleware.js`: auth helpers and constants.
- `lilith-logger.js`: structured logger with JSON output.
- `vault-config-loader.js`: helper to fetch secrets/config from Vault.
- `apm-exporter.js`: optional APM exporter wiring (best-effort).

Prefer importing from the top-level package (`@lilith/service-lib`) or the entrypoints above rather than deep paths that are not part of the supported surface. If you need a new exported helper, add it to `index.js` and document it here.

## Module system
- Package uses ESM (`"type": "module"`) and NodeNext resolution. Keep relative imports with explicit extensions.
- Jest configs should treat `.js` and `.ts` as ESM (see root `jest.config.base.cjs`).
- Compatibility shims that must stay CommonJS live in `.cjs` files; keep them isolated.

## Generated type artifacts
- Thousands of `.d.ts`/`.d.ts.map`/`.js.map` files can be produced by tooling—treat them as build artifacts.
- Only the curated type surfaces in the root and `types/` directory are tracked. Everything else is ignored by `.gitignore`.
- Use `npm run clean:types` to delete stray generated artifacts and keep the workspace lean.
- Use `npm run analyze:types` to get a quick count of type artifacts present in this package.

## Maintenance checklist
- Add new helpers to `index.js` and note the entrypoint above so downstream services import consistently.
- Keep tests in `__tests__/` and prefer Fastify injection over listening on a port.
- When adding new build outputs, update `.gitignore` to prevent accidental commits.