ADR-0003 - Env vars override target presets #

• Status: Superseded by ADR-0017
• Date: 2026-05-07
• Deciders: Natan

Context #

Each environment (production, development, localhost) has a default set of URLs (API, S3 endpoint, S3 bucket). We sometimes want to point the runner at a one-off URL - a preview deployment, an ephemeral env, a developer's local instance - without editing code.

Two paths:

1. Code is canonical. Always use the preset for the chosen env;

force code edits for ad-hoc runs.

1. Env overrides preset. If SNAPPY_API_URL is set, it wins;

otherwise fall back to the preset.

Decision #

src/config/targets.ts resolves each target as env.SNAPPY_X ?? PRESETS[env.SQA_ENV].x. Env wins.

Consequences #

• Pro: Ad-hoc runs against any URL with no code change:

SNAPPY_API_URL=https://preview-pr-123.metaintro.com make run.

• Pro: Defaults stay readable in targets.ts (PRESETS is

declarative, not a chain of ??).

• Con: A stale env var in .env silently overrides the preset.

Mitigated because .env is gitignored and per-developer.

• Falsifiability: Revisit if we hit an incident traced to a

forgotten env override winning over a corrected preset. Add a startup log line listing resolved targets if so (already implemented as the "▶ sqa run started" line).