SPEC — F-004 Typed config and feature flags

Problem

Risky features need activation separate from deployment; env access must be typed. Today env access is ad-hoc (process.env.X ?? fallback scattered in entrypoints) and there is no activation mechanism distinct from deploy.

Goal

Fail-fast typed config plus a simple feature flag module behind an interface.

Scope IN

Typed env config loader in src/infrastructure/config, fail fast on missing/invalid required vars (all problems reported in one clear message)
FeatureFlagProvider interface with simple in-memory store implementation (src/modules/flags)
Deployment ≠ activation: flags seed from FLAG_* env vars at boot and can be mutated at runtime without redeploy
DB pool refactor to consume config instead of sniffing env itself

Scope OUT

No external flag service
No per-user segmentation
No admin HTTP endpoint for flags yet (first consumer decides shape; store API is runtime-mutable already)

Required vs optional vars

Var	Required	Default
DATABASE_URL	yes	—
PORT	no	3000 (valid: integer 1–65535)
HOST	no	0.0.0.0
LOG_LEVEL	no	info
NODE_ENV	no	development (valid: development/test/production)
REDIS_URL	no	undefined
FLAG_	no	parsed as true/false

Acceptance criteria

Given a missing required env var When the app starts Then startup fails with a clear message naming the var.
Given flag off When a code path guarded by the flag runs Then the path is skipped.
Flag state change does not require redeploy (runtime setEnabled on the store).
./scripts/verify.sh green.

Non-functional

No new dependencies: hand-rolled validation is small, explicit and boring.
Config loader is a pure function of an env object (testable without touching process.env).

1.8 KiB Raw Blame History Unescape Escape