Proposal: deprecate load(), loadSync() and @std/dotenv/load in favor of --env-file

[tomas-zijdemans]

Summary

I propose deprecating load(), loadSync() and the @std/dotenv/load side-effect module in favor of the runtime's --env-file flag. parse() and stringify() are not affected: they have no built-in equivalent and should stay.

Motivation

The common use case for this package is loading a .env file into the process environment before your code runs. That's been built into the CLI since Deno 1.38 and stable through 2.x, including multiple files (--env-file=.env --env-file=.env.local). Node and Bun ship the same flag, so the cross-runtime story holds.
This was proposed once before in #3604 and closed with "let's revisit if --env gets adoption." Two things have changed since. The flag is now stable and mature, and #7208 set a precedent for deprecating std modules that duplicate built-ins. Even in #3604 the sentiment was already "drop the loaders, keep parse and stringify". This proposal is exactly that.
Worth noting: @std/dotenv sits at 0.225.7 because it was excluded from the stabilization effort (#4600) over precisely this overlap. Deprecating the loaders resolves the question that's kept it unstable.

Migration

@std/dotenv API	Replacement
import "@std/dotenv/load"	deno run --env-file app.ts
load({ export: true }) / loadSync({ export: true })	--env-file
load({ envPath: "./.env_prod" })	--env-file=.env_prod
load() (read into an object, no export)	parse(await Deno.readTextFile(".env"))

Known gaps

• load() returns the parsed config as an object without touching the environment. The parse() composition above covers this, minus the silent skip when the file is missing.
• load() accepts a path at runtime. A CLI flag can't do that, but parse() plus a file read can.
• The parsing rules may not match the flag's parser exactly, e.g. expansion like ${KEY:-default}. Needs verification before the deprecation PR lands, and documenting in the migration notes either way.

Plan

1. Land a deprecation PR adding @deprecated JSDoc tags to load(), loadSync(), LoadOptions and the /load export, and rewrite the module docs into a migration guide.
2. Remove the deprecated exports in a later minor (the package is 0.x, so no major is needed).
3. With the loaders gone, revisit stabilizing what remains as @std/dotenv@1 with parse() and stringify().
   Ref Proposal: deprecate @std/testing/bdd and @std/testing/snapshot in favor of built-ins #7208, Feedback on proposal: Deprecate std/dotenv #3604, suggestion: deprecate std/dotenv's load() #4019, proposal: drop std/dotenv from the first stabilization target #5331