feat: #5 add .env config file support

[TheRealAgentK]

#5: add .env config file support

Closes #5.

Description 📝

• Purpose: Implements the long-standing request from issue Support config file for arguments like the app-id #5: let users configure raygun-cli via a project-root config file instead of having to pass every credential as a CLI argument or environment variable on every invocation. This is a follow-up to perf: #5 refactor config props #15, which restructured ConfigProp so each property is loaded independently — a prerequisite for adding a third source.
• Approach: Adds a third resolution tier to ConfigProp.load(). Lookup order (highest priority first): CLI argument → environment variable → .env file. The .env is discovered automatically (CWD, then walking up parent directories to $HOME) or explicitly via a new --config-file=<path> global flag. Parsing uses the dotenv package so we get correct handling of quoted values, # comments, export KEY=value syntax, and other .env conventions out of the box.

Type of change

• New feature (non-breaking change which adds functionality)
• This change requires a documentation update

Updates

👉 New lib/src/config_file.dart: ConfigFile class with discovery (walks parent dirs, stops at $HOME), explicit-path support, dotenv parsing, and a singleton + setInstance/resetForTest test seam mirroring Environment.
👉 lib/src/config_props.dart: extended load() to fall through to the .env file when arg + env are both absent. Updated error message to mention all three sources.
👉 bin/raygun_cli.dart: added --config-file=<path> global flag and initializes ConfigFile before any subcommand runs.
👉 New dependencies: dotenv: ^4.2.0 and path: ^1.9.0 (the latter was already transitive — promoted to direct since we use it directly).
👉 README + AGENT.md updated, sample example/.env.example committed.
👉 Opportunistic test debt cleanup (separate commits): added previously missing tests for Environment (singleton, [] operator) and RaygunMultipartRequestBuilder / RaygunPostRequestBuilder (the shared HTTP request builders used by every command).

Test plan 🧪

The PR ships with +68 net new tests (58 → 126 total). All green locally and in CI:

dart format .   # clean
dart analyze    # no issues
dart test       # 126/126 pass

Test coverage breakdown for the new feature:

Test file	Tests	Layer
test/config_file_test.dart	21	Unit (discovery, parsing, singleton)
test/config_props_test.dart	13 (was 4)	Integration (precedence chain across all 3 sources)
test/e2e_config_file_test.dart	9	E2E — spawns real CLI subprocess
test/environment_test.dart	11	Infrastructure (was 0)
test/core/raygun_api_test.dart	18	Infrastructure (was 0)

Manual smoke test (with verbose output to confirm values flow through):

mkdir -p /tmp/raygun-cli-smoke
cat > /tmp/raygun-cli-smoke/.env <<EOF
RAYGUN_TOKEN=smoke-token-xyz
RAYGUN_API_KEY=smoke-api-key-abc
EOF
cd /tmp/raygun-cli-smoke
dart run /path/to/bin/raygun_cli.dart -v deployments --version=1.2.3
# Expect to see:
#   Loaded config from /tmp/raygun-cli-smoke/.env
#   token: smoke-token-xyz
#   api-key: smoke-api-key-abc
#   ...
#   Error creating deployment: 401  (expected — fake creds)

Reviewers can also try:

• --config-file=<path> to point at an explicit file
• Mixing arg + env + file to verify precedence
• Running from a nested directory to verify upward discovery
• Removing all sources to verify exit code 2 with the new error message

Backward compatibility

This is an additive change:

• Missing .env is a silent no-op — existing scripts using args or env vars are unaffected.
• All pre-existing tests still pass without modification.
• No existing CLI flags or env vars changed semantics.

Author to check 👓

• Project and all contained modules builds successfully
• Self-/dev-tested
• Unit/UI/Automation/Integration tests provided where applicable
• Code is written to standards
• Appropriate documentation written (code comments, internal docs)

Reviewer to check ✔️

• Project and all contained modules builds successfully
• Change has been dev-/reviewer-tested, where possible
• Unit/UI/Automation/Integration tests provided where applicable
• Code is written to standards
• Appropriate documentation written (code comments, internal docs)