typescript-env-example-config-surface-drift

Answer

Root cause. apps/api/src/config/env.ts declares 32 keys in a z.object({ ... }) schema (each KEY: at two-space indent), but .env.example only documented 17. The 15 undeclared vars were missing entirely — drift caused by schema additions never being propagated to the example file. A dev loading the example config would silently fall back to Zod defaults or, for required keys, fail at boot with no documentation of what to set.

The mechanical fix — two pieces:

1. Verification gate (scripts/check-env-example.mjs): the scripted diff from the problem spec — extract ^ [A-Z0-9_]+: keys from env.ts, assert each appears in .env.example allowing commented lines, fail (exit 1) with the missing list on drift.

const KEY_RE = /^  ([A-Z0-9_]+):/gm;                       // 2-space-indented `KEY:` in the Zod object
const schemaKeys = [...envTs.matchAll(KEY_RE)].map((m) => m[1]);
for (const line of envExample.split(/\r?\n/)) {
  const m = line.match(/^\s*#?\s*([A-Z0-9_]+)=/);         // active OR commented `KEY=` (whitespace tolerant)
  if (m) present.add(m[1]);
}
const missing = uniqueKeys.filter((k) => !present.has(k)); // exit 1 if any

1. Idempotent sync script (scripts/sync-env-example.mjs): appends every missing key as a commented line whose value is the literal Zod default, exactly per the mechanical-fix spec. Existing entries are never rewritten; running it on a clean tree is a no-op.

const DEFAULT_RE = /\.default\(\s*"([^"]*)"\s*\)|\.default\(\s*'([^']*)'\s*\)|\.default\(\s*([^()]*?)\s*\)/;
// for each missing `KEY:` → append `# KEY=<default>` (empty for optional/required w/o default)

Applied to the drifted file, the diff is purely additive — the 15 added lines (all commented, values taken from the schema):

+ # DATABASE_SSL=true           + # RATE_LIMIT_WINDOW_MS=60000
+ # REDIS_CACHE_TTL=3600        + # SMTP_USER=
+ # REFRESH_TOKEN_TTL=604800    + # SMTP_PASS=
+ # BCRYPT_ROUNDS=12            + # SMTP_FROM=
+ # SENTRY_TRACES_SAMPLE_RATE=0.1  + # UPLOAD_DIR=./uploads
+ # MAX_FILE_SIZE_MB=25         + # OPENAI_MODEL=gpt-4o-mini
+ # WEBHOOK_SECRET=             + # API_VERSION=v1
+ # ENABLE_METRICS=false

Convention: keys with a Zod .default(...) are documented as # KEY=<default> (uncomment to override); required keys stay active with operator placeholders; optional vars without a default are # KEY=.