config-management

---
name: config-management
description: >-
  Centralizes typed configuration with validated env loading, fail-fast startup,
  and no scattered process.env reads. Use this skill when adding config,
  environment variables, feature flags, or startup validation in TypeScript
  services. Do not use when/for validating untrusted HTTP input at the edge (use
  validation-boundary) or secrets rotation runbooks.
version: 1.2.0
libraries: ["node-env-resolver", "zod"]
---

# Config Management

## Critical rules

- Validate the entire config once at startup. Bad config fails the process before traffic.
- Never read `process.env` mid-request. Resolve once; inject typed config through `deps`.
- Keep secrets out of the environment: load from a secret manager into memory (`preventProcessEnvWrite`).
- No fallback defaults for required values — fail fast.
- Prefer ephemeral/rotating credentials; scan git history for secrets in CI.
- Before implementing loaders or tests, read [references/examples.md](references/examples.md) and [references/testing.md](references/testing.md).

## Workflow

1. Define the config schema (node-env-resolver validators or Zod).
2. Resolve at startup: non-secrets from env, secrets from secret manager into memory.
3. Wire typed config into the composition root `deps`.
4. Make `getConfig(resolvers?)` injectable so tests pass mock resolvers — see [references/testing.md](references/testing.md).
5. Add TruffleHog/Gitleaks over full history in CI.
6. Prefer short-lived credentials with refresh where available.

## Resources

- [references/examples.md](references/examples.md) — resolver/Zod loaders, deps injection, secrets, fail-fast. Read when implementing.
- [references/testing.md](references/testing.md) — env variants, mock resolvers, CI scanning, rationalizations. Read for tests and hardening.

## Validation

- [ ] Config validated once at startup; process exits on failure
- [ ] No required value has a silent default
- [ ] Config injected via `deps`, not re-read from `process.env`
- [ ] Secrets from secret manager with `preventProcessEnvWrite`
- [ ] Config type inferred from schema
- [ ] Tests inject mock resolvers/config objects
- [ ] CI secret-scans full git history

## Constraints

- Per-request HTTP input is `validation-boundary`, not this skill. Dynamic feature-flag evaluation is separate from startup config.
- Related: `validation-boundary`, `fn-args-deps`, `strict-typescript`, `observability`.

• SKILL.md 2 KB
• references/examples.md 3 KB
• references/testing.md 3 KB