@luckystack/core 0.10.1 → 0.11.0

package/docs/app-bootstrap.md

@@ -1,452 +1,7 @@
-# App Bootstrap
+# App bootstrap
 
-> Deep specs for the registries + utilities a project entry wires at boot: bind address, runtime maps, api-method map, prisma/redis clients, notifier, email senders, logger + redacted log keys, locale reloader, boot UUID, synchronized env hashes, plus the cross-cutting helpers `tryCatch`, `sleep`, `getParams`, `serveAvatar`. Source: `packages/core/src/`. Bijgewerkt: 2026-07-20.
+The registry pattern separates framework packages from each application's infrastructure. Register dependencies during boot and read them when needed, rather than importing consumer configuration or caching stale values at module load. The server entry performs standard wiring; take over registration manually only when owning boot order yourself. See `../src/createRegistry.ts`, `../src/clients.ts`, `../../server/src/bootstrap.ts`.
 
-## Overview
+A consumer-supplied client is intentional ownership: automatic secret refresh must not replace a custom Redis or database connection without its owner's consent. Logging and tracking contexts must redact credentials before fanout; production should not install stack-trace-heavy development logging. The runtime/deploy-environment distinction matters: deployment identity does not authorize development behavior. See `../src/redis.ts`, `../src/env.ts`, `../src/redactedLogKeys.ts`.
 
-The core package exposes a uniform "register at boot, read at call time" pattern across many DI slots. A consumer's boot entry calls every relevant `register*` function once, before framework hot paths run. Framework packages then read via `get*` accessors and never reach around the registry.
-
-This doc groups every slot into sections:
-
-- **Bind address** — `createLuckyStackServer` writes the resolved listen address so CORS code reads it from one source.
-- **Runtime maps + api method map** — the project's generated route maps are injected via a provider, so the api/sync packages can resolve route handlers without relative imports into the consumer tree.
-- **Prisma + Redis clients** — DI slots with lazy defaults; `prisma` and `redis` are proxies that defer resolution to call time.
-- **Notifier** — client-side toast slot used by `apiRequest`, `syncRequest`, and the offline-queue flush.
-- **Email senders** — multi-adapter registry (`'default'`, `'transactional'`, `'marketing'`, custom) with a legacy single-sender path.
-- **Logger + redacted log keys** — pluggable logger (default = console; dev factory available) plus a set of keys masked when printing payloads.
-- **Locale reloader** — devkit watcher trigger point.
-- **Boot UUID + synchronized env hashes** — router cross-env handshake primitives.
-- **Misc utilities** — `tryCatch`, `sleep`, `getParams`, `serveAvatar`.
-
-## API Reference — Runtime Port Override + Bind Address
-
-### `registerPortOverride(port: number | null): void` / `getPortOverride(): number | undefined`
-
-Browser-safe registry exported from both `@luckystack/core/config` and the main barrel. `@luckystack/server/parseArgv` registers the positional CLI port before consumer `config.ts` evaluates; `null` clears it. This is runtime override state only — the static default remains consumer-owned `config.ports.ts`. Values outside integer `0..65535` throw.
-
-### `registerBindAddress(address: { ip: string; port: number; configuredPort?: number }): void`
-
-Stores the intended pre-listen address used by `createLuckyStackServer` and resets the OAuth pre-hop baseline. Optional `configuredPort` records the consumer default below a programmatic/argv override, so OAuth can update a callback that still names that default without bypassing an unrelated local router ingress. Framework code never needs to infer the listen port from env vars.
-
-### `registerBoundAddress(address: { ip: string; port: number }): void`
-
-Called from the successful `node:http.listen` callback with `httpServer.address().port`. Updates the address all runtime readers see while preserving the intended address. The distinction matters for `listen(0)` and for a dev auto-increment hop.
-
-### `getBindAddress(): { ip: string; port: string }`
-
-**Behavior (resolution order):**
-1. Actually-bound registered value (returns `{ ip: registered.ip, port: String(registered.port) }`).
-2. `process.env.SERVER_IP` for the pre-bootstrap bind address.
-3. Fallback to `'127.0.0.1'` / the generic server port `'80'`. A real server registers its intended `options.port` / argv / `defaultPort` before request-time CORS or OAuth resolution.
-
-### `resolveDevCallbackUrl(callbackUrl: string): string`
-
-In non-production environments, rewrites a `localhost`, `127.0.0.1`, or `[::1]` OAuth callback only when its effective port still equals the intended pre-listen port or the registered consumer default and the server uses another port. Authorize and token exchange both call this helper, so their `redirect_uri` remains byte-identical. An explicitly configured local router/reverse-proxy port that matches neither is left untouched. Production, remote hosts, malformed URLs, and already-current callbacks are no-ops.
-
-## API Reference — Runtime Maps
-
-### Types
-```typescript
-export interface RuntimeApiMapsResult {
-  apisObject: Record<string, unknown>;
-  functionsObject: Record<string, unknown>;
-}
-
-export interface RuntimeSyncMapsResult {
-  syncObject: Record<string, unknown>;
-  functionsObject: Record<string, unknown>;
-}
-
-export interface RuntimeMapsProvider {
-  getRuntimeApiMaps: () => Promise<RuntimeApiMapsResult>;
-  getRuntimeSyncMaps: () => Promise<RuntimeSyncMapsResult>;
-}
-```
-
-### `registerRuntimeMapsProvider(provider: RuntimeMapsProvider): void`
-
-Stores a provider. The project's `server/prod/runtimeMaps.ts` knows how to dynamically import per-preset `generatedApis.<preset>.ts` files and merge devkit overrides — framework packages don't. They ask core for the current maps and core delegates.
-
-### `getRuntimeApiMaps(): Promise<RuntimeApiMapsResult>`
-### `getRuntimeSyncMaps(): Promise<RuntimeSyncMapsResult>`
-
-Async accessors. Default (unregistered) returns empty `{ apisObject: {}, functionsObject: {} }` / `{ syncObject: {}, functionsObject: {} }` so framework code can boot in tests without crashing — but every api/sync route silently 404s in that mode.
-
-### `isRuntimeMapsProviderRegistered(): boolean`
-
-Used by `verifyBootstrap` (in `@luckystack/server`) to detect the production fail-mode where no provider got registered — typically because the project forgot to import its `server/prod/runtimeMaps.ts` side-effect.
-
-## API Reference — API Method Map
-
-### Types
-```typescript
-export type HttpMethodLiteral = 'GET' | 'POST' | 'PUT' | 'DELETE';
-export type ApiMethodMap = Record<string, Record<string, Record<string, HttpMethodLiteral>>>;
-```
-
-Shape: `apiMethodMap[pagePath][apiName][version] = 'GET' | ...`.
-
-### `registerApiMethodMap(map: ApiMethodMap): void`
-
-Stores the generated method map. The canonical consumer wrapper `src/_sockets/apiRequest.ts` imports `apiMethodMap` from `apiTypes.generated.ts`, registers it at module load, then re-exports the core request helper. This registration is required for routed HTTP because route names alone cannot reliably reveal their declared HTTP method.
-
-### `getRegisteredApiMethod(pagePath, apiName, version): HttpMethodLiteral | undefined`
-
-Returns the registered method or `undefined`. `isGetMethod` (in `apiRequest.ts`) falls back to the `inferHttpMethod` prefix heuristic when undefined.
-
-### `isApiMethodMapRegistered(): boolean`
-
-Detects whether the prefix-heuristic fallback is active.
-
-## API Reference — Prisma + Redis Clients
-
-### `registerPrismaClient(client: PrismaClient): PrismaClient`
-### `registerRedisClient(client: RedisClient): RedisClient`
-
-Stores a custom client and returns it for chaining. Replaces (last-write-wins).
-
-### `getPrismaClient(): PrismaClient`
-### `getRedisClient(): RedisClient`
-
-**Behavior (resolution order):**
-1. Registered client.
-2. Default resolver (set by `db.ts` / `redis.ts` at module load with the lazy factory).
-3. Throws when neither exists ("No Prisma/Redis client available...").
-
-### `isPrismaClientRegistered(): boolean`
-### `isRedisClientRegistered(): boolean`
-
-Boot guards.
-
-### `setDefaultPrismaResolver(resolver)` / `setDefaultRedisResolver(resolver)`
-
-Internal — wired by `db.ts` / `redis.ts`. Splits registration from default construction so this file doesn't depend on `@prisma/client` / `ioredis` types directly.
-
-## API Reference — Notifier
-
-### Types
-```typescript
-export interface NotifyParam { key: string; value: string | number | boolean }
-export interface NotifyInput { key: string; params?: NotifyParam[] }
-export interface Notifier {
-  success: (input: NotifyInput) => void;
-  error: (input: NotifyInput) => void;
-  info: (input: NotifyInput) => void;
-  warning: (input: NotifyInput) => void;
-}
-```
-
-### `registerNotifier(notifier: Notifier): void`
-
-Replaces the active notifier. Default is a no-op (safe for SSR / tests).
-
-### `getNotifier(): Notifier`
-
-Returns the active notifier.
-
-### `notify: Notifier`
-
-A delegating wrapper used by framework hot paths so framework code can do `notify.error({ key: 'api.failed' })` without dereferencing on every call.
-
-## API Reference — Email Senders
-
-### Types
-```typescript
-export interface EmailMessage {
-  to: string | string[];
-  subject: string;
-  html: string;
-  text?: string;
-  from?: string;
-  replyTo?: string;
-  cc?: string | string[];
-  bcc?: string | string[];
-}
-
-export type EmailResult =
-  | { ok: true; id: string }
-  | { ok: false; reason: string; cause?: unknown };
-
-export interface EmailSender {
-  name: string;
-  send: (message: EmailMessage) => Promise<EmailResult>;
-}
-
-export type EmailSenderRegistry = Record<string, EmailSender>;
-```
-
-### `registerEmailSender(sender: EmailSender): void`
-
-Legacy single-sender. Mirrors the sender into `registry.default` so `getEmailSenderByName('default')` finds it.
-
-### `registerEmailSenders(senders: EmailSenderRegistry): void`
-
-Multi-adapter. Replaces the entire registry (last-write-wins). If `senders.default` exists, also updates the legacy slot.
-
-Reserved slot conventions:
-- `'default'` — fallback when no specific slot matches.
-- `'transactional'` — login password-reset, account-confirmation, security-critical mail.
-- `'marketing'` — newsletters, bulk sends.
-- `'diagnostics'` — diagnostic endpoints (e.g. playground).
-
-Custom slots ('billing', 'support') are allowed and resolved explicitly via `sendEmail({ adapter: 'billing', ... })` in `@luckystack/email`.
-
-### `getEmailSender(): EmailSender | null`
-
-Returns the legacy sender, falling back to `registry.default`. `null` when neither is set.
-
-### `getEmailSenderByName(name: string): EmailSender | null`
-
-**Behavior:**
-- Returns `registry[name]` when present.
-- Falls back to the legacy single sender when `name === 'default'`.
-- Returns `null` otherwise.
-
-### `listEmailSenderNames(): string[]`
-
-Returns the registry keys (excludes the legacy single-sender slot).
-
-### `isEmailSenderRegistered(): boolean`
-
-True when either the legacy slot or the registry is populated.
-
-## API Reference — Logger
-
-### Types
-```typescript
-export interface LoggerContext { [key: string]: unknown }
-
-export interface Logger {
-  debug: (message: string, context?: LoggerContext) => void;
-  info: (message: string, context?: LoggerContext) => void;
-  warn: (message: string, context?: LoggerContext) => void;
-  error: (message: string, error?: unknown, context?: LoggerContext) => void;
-}
-```
-
-### `registerLogger(logger: Logger): void`
-
-Replaces the active logger and sets the registered flag.
-
-### `getLogger(): Logger`
-
-Returns the active logger. Default is a thin wrapper over `console.{debug,info,warn,error}` with no color codes — safe for production.
-
-### `isLoggerRegistered(): boolean`
-
-Boot guard.
-
-### `createDevLogger(): Logger`
-
-Returns a logger that calls `console.log(message[, context], '<color>')`. The trailing color string is only meaningful after `initConsolelog()` installed the console monkey-patch — without it the codes print as literal text.
-
-### `resetLoggerForTests(): void`
-
-Test-only — restores the default logger and clears the registered flag.
-
-### `initConsolelog(): void`
-
-Monkey-patches `console.log` to:
-- Capture the caller's frame from the stack (skipping `consoleLog.ts` and `loggerRegistry.ts` frames).
-- Strip the platform-specific path prefix and column suffix from the frame, yielding a `<file>:<line>` label.
-- Find any color keyword in the args (`black`, `red`, `green`, `yellow`, `blue`, `magenta`, `cyan`, `white`, `reset`), remove it, and apply the ANSI color around the file label.
-- If the first arg is an object, print the label first then the args on a new line; otherwise concatenate with `' -- '` separator.
-
-Dev-only. Never install in production — stack-trace per log is expensive.
-
-## API Reference — Redacted Log Keys
-
-Default seed set: `password`, `confirmpassword`, `token`, `newtoken`, `authorization`, `cookie`, `set-cookie`. Stored lowercased.
-
-### `registerRedactedLogKeys(keys: readonly string[]): void`
-
-Additive — adds each lowercased key to the set. Idempotent on duplicates.
-
-### `getRedactedLogKeys(): readonly string[]`
-
-Returns a fresh array of the current set (lowercased).
-
-### `isRedactedLogKey(key: string): boolean`
-
-Case-insensitive lookup used inside framework log-redaction.
-
-### `resetRedactedLogKeysForTests(): void`
-
-Test-only — clears and re-seeds with the default set.
-
-## API Reference — Locale Reloader
-
-### `registerLocaleReloader(reloader: LocaleReloader): LocaleReloader`
-
-Stores a `() => void | Promise<void>` callback and returns it. The consumer's i18n loader registers it; `@luckystack/devkit`'s file watcher calls it when `_locales/*.json` changes.
-
-### `getLocaleReloader(): LocaleReloader | null`
-
-Returns the registered reloader, or `null` when none was supplied (watcher no-ops in that case).
-
-## API Reference — Boot UUID + Env Sync
-
-### Constants
-
-| Name | Value |
-|---|---|
-| `BOOT_KEY_PREFIX` | `'luckystack:boot:'` |
-| (internal) `DEFAULT_BOOT_KEY_TTL_SECONDS` | `3600` |
-
-`BOOT_KEY_PREFIX` is exported as the single source of truth so `@luckystack/router`'s `bootHandshake.ts` cannot drift.
-
-### Runtime mode versus deploy environment
-
-- `resolveRuntimeMode()` returns the validated `NODE_ENV` application mode (`development`, `production` or `test`). `isProductionRuntime()` and `isTestRuntime()` are convenience predicates. Security, route-map, cookie and dev-tool behavior uses this axis.
-- `resolveEnvKey()` returns `process.env.LUCKYSTACK_ENV` ?? `process.env.NODE_ENV` ?? `'development'`. This is only the deploy-topology identity used by boot UUIDs, health attestation, routing and observability labels. A production process may therefore use `LUCKYSTACK_ENV=staging` without enabling development behavior.
-
-### `writeBootUuid(envKey?: string): Promise<string>`
-
-**Behavior:** Generates a fresh `randomUUID()` and writes it to `luckystack:boot:<envKey>` in Redis with `EX <deployConfig.routing.bootKeyTtlSeconds ?? 3600>`. Returns the UUID.
-
-### `readBootUuid(envKey?: string): Promise<string | null>`
-
-Reads the UUID for the given env key (defaults via `resolveEnvKey()`).
-
-### `refreshBootUuid(envKey?: string): Promise<void>`
-
-Extends the existing key with the configured TTL without changing its UUID. If
-Redis recovered after the key had already expired, writes a fresh UUID instead.
-The key is environment-level: every healthy backend may renew the current value,
-so multi-instance readiness does not depend on the last process that wrote it.
-
-### `startBootUuidHeartbeat(envKey?: string): BootUuidHeartbeat`
-
-Starts an unref'd refresh loop at one third of the configured TTL. Each refresh
-must settle before the next timer is scheduled, preventing overlapping Redis
-calls during an outage. Failures are logged and retried. Call `stop()` during
-server shutdown. `@luckystack/server` starts this only after HTTP listen succeeds.
-
-### `collectSynchronizedEnvKeys(): string[]`
-
-Walks `deployConfig.resources` and collects every `synchronizedEnvKeys[]` entry into a sorted unique list.
-
-### `computeSynchronizedEnvHashes(): Record<string, string | null>`
-
-For each key from `collectSynchronizedEnvKeys`, returns a SHA-256 hex hash of `process.env[key]` (or `null` when the var is unset). Used by `/_health` so the router can compare hashes across environments without leaking secrets.
-
-### `hashSynchronizedValue(value: string): string`
-
-Router-side helper — hash a single value with the same algorithm. Kept separate so the router can import it without loading the core barrel (which opens a Redis connection).
-
-## API Reference — Utilities
-
-### `tryCatch<T, P>(fn, params?, context?): Promise<[Error | null, T | null]>`
-
-**Signature:**
-```typescript
-export default async function tryCatch<T, P>(
-  func: (values: P) => Promise<T> | T,
-  params?: P,
-  context?: Record<string, unknown>,
-): Promise<[Error | null, T | null]>
-```
-
-**Behavior:**
-- Calls `func(params)`, awaits the result.
-- On success → returns `[null, response]`.
-- On throw → calls `captureException(error, context)` (legacy + multi-adapter fan-out) and returns `[error as Error, null]`.
-
-**Usage convention:** check the first tuple element; if truthy, an error occurred.
-
-```typescript
-import { tryCatch } from '@luckystack/core';
-
-const [error, result] = await tryCatch(async () => db.user.findUnique({ where: { id } }));
-if (error) return { status: 'error', errorCode: 'db.failed' };
-const user = result;
-```
-
-### `sleep(ms: number): Promise<void>`
-
-Resolves after `setTimeout(ms)`. Used in fanout-yield loops and dev-mode hot reload debouncing.
-
-### `getParams({ method, req, res, queryString? }): Promise<Record<string, unknown> | null>`
-
-**Behavior:**
-- `GET` → returns `Object.fromEntries(new URLSearchParams(queryString))`.
-- `POST` / `PUT` / `DELETE`:
-  - Checks the declared `Content-Length` against `projectConfig.http.requestBodyMaxBytes`. If exceeded → writes a 413 JSON error response with `errorCode: 'api.payloadTooLarge'` and resolves `null`.
-  - Streams `req.on('data')`; aborts with the same 413 if running body size exceeds the cap.
-  - Parses `application/x-www-form-urlencoded` via `URLSearchParams`.
-  - Parses `application/json` via `JSON.parse(body || '{}')`. Rejects array / scalar / null bodies — only plain objects pass.
-  - Unknown / missing content-type → 415 with `errorCode: 'api.unsupportedMediaType'`.
-  - Malformed JSON / form → 400 with `errorCode: 'api.invalidRequestFormat'`.
-
-**Returns:** Parsed object, or `null` when the framework already wrote an error response.
-
-### `serveAvatar({ routePath, res }): Promise<void>`
-
-**Behavior:**
-1. Resolves `uploadsFolder = getUploadsDir()`.
-2. Strips the extension from `routePath` → `fileId`.
-3. Rejects when `!fileId` or `fileId` does not match `/^[A-Za-z0-9_-]{1,128}$/` → 404 plaintext. Belt-and-suspenders against path traversal even though `path.basename` already strips separators.
-4. Reads `getAvatarConfig()` and walks `formats` in order:
-   - For each `{ extension, contentType }`, checks `access(<uploadsFolder>/<fileId>.<extension>)` via `tryCatch`. First existing file wins.
-   - Writes 200 with `Content-Type` + `Cache-Control` from the avatar config and pipes the file stream to `res`.
-5. If no format matches → logs `avatar: file not found` at debug and writes 404 plaintext.
-
-## Environment variables read by core
-
-| Var | Default | Where |
-|---|---|---|
-| `NODE_ENV` | `'development'` | `env.ts` (Zod-validated). |
-| `SERVER_IP` | `'127.0.0.1'` | `getBindAddress` fallback. |
-| `SECURE` | `'false'` | `allowedOrigin` scheme selection. |
-| `REDIS_HOST` | `'127.0.0.1'` | Default redis client. |
-| `REDIS_PORT` | `'6379'` | Same. |
-| `REDIS_USER` | (unset) | Optional ioredis auth. |
-| `REDIS_PASSWORD` | (unset) | Optional ioredis auth. |
-| `PROJECT_NAME` | `'luckystack'` | `getProjectName` fallback. |
-| `LUCKYSTACK_ENV` | (unset) | `resolveEnvKey` first preference. |
-
-## Example — minimal project boot
-
-```typescript
-import {
-  registerProjectConfig,
-  registerPrismaClient,
-  registerRedisClient,
-  registerLogger,
-  registerNotifier,
-  registerRuntimeMapsProvider,
-  registerBindAddress,
-} from '@luckystack/core';
-import { PrismaClient } from '@prisma/client';
-import Redis from 'ioredis';
-
-registerProjectConfig({ defaultLanguage: 'en' });
-registerPrismaClient(new PrismaClient({ log: ['warn', 'error'] }));
-registerRedisClient(new Redis(process.env.REDIS_URL!));
-registerLogger({
-  debug: (...a) => pino.debug(a),
-  info:  (...a) => pino.info(a),
-  warn:  (...a) => pino.warn(a),
-  error: (...a) => pino.error(a),
-});
-registerNotifier(toastNotifier);
-registerRuntimeMapsProvider(prodRuntimeMaps);
-registerBindAddress({ ip: '0.0.0.0', port: 8080 });
-```
-
-The browser-side method map is registered separately by the project wrapper:
-
-```typescript
-import { registerApiMethodMap } from '@luckystack/core/client';
-import { apiMethodMap } from './apiTypes.generated';
-
-registerApiMethodMap(apiMethodMap);
-export { apiRequest } from '@luckystack/core/client';
-```
-
-## Related
-
-- Function INDEX: `packages/core/CLAUDE.md`
-- Architecture: `docs/ARCHITECTURE_PACKAGING.md`, `docs/ARCHITECTURE_ROUTING.md`, `docs/HOSTING.md`, `docs/ARCHITECTURE_EXTENSION_POINTS.md`
-- README: `packages/core/README.md`
-- Source: `packages/core/src/bindAddress.ts`, `runtimeMapsRegistry.ts`, `apiMethodMapRegistry.ts`, `clients.ts`, `db.ts`, `redis.ts`, `notifier.ts`, `emailRegistry.ts`, `loggerRegistry.ts`, `redactedLogKeys.ts`, `consoleLog.ts`, `localeReloader.ts`, `bootUuid.ts`, `synchronizedEnvHashes.ts`, `tryCatch.ts`, `sleep.ts`, `getParams.ts`, `serveAvatars.ts`
+For the available registrations and environment variables, consult their types and use sites in `../src/`, not a copied list.