docs: add comprehensive JSDoc documentation for environment variables (#10175)

* docs: add comprehensive JSDoc documentation for environment variables

- Document all user-facing environment variables in VariableNames type
- Organize by category: auth, development, logging, build, advanced
- Exclude internal CI variables as requested in issue #9617
- Follow existing documentation patterns from misc-variables.ts

Resolves #9617

Co-Authored-By: [email protected] <[email protected]>

* docs: address PR feedback - improve environment variable descriptions

- Combine HTTPS key/cert paths with better explanation
- Clarify API key is legacy and API token is preferred
- Add context about compliance region affecting API/AUTH URLs
- Clarify Hyperdrive connection string wildcard usage
- Use 'Wrangler config' instead of 'wrangler.toml'
- Improve overall clarity and accuracy of descriptions

Addresses feedback from @petebacondarwin

Co-Authored-By: [email protected] <[email protected]>

---------

Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Co-authored-by: [email protected] <[email protected]>

Author: devin-ai-integration[bot]

packages/wrangler/src/environment-variables/factory.ts

@@ -1,5 +1,56 @@
 import { UserError } from "../errors";
 
+/**
+ * Environment variables supported by Wrangler for configuration and authentication.
+ *
+ * ## Authentication & API Configuration
+ *
+ * - `CLOUDFLARE_ACCOUNT_ID` - Overrides the account ID for API requests. Can also be set in Wrangler config via `account_id` field.
+ * - `CLOUDFLARE_API_TOKEN` - API token for authentication. Preferred over API key + email.
+ * - `CLOUDFLARE_API_KEY` - Legacy API key for authentication. Requires CLOUDFLARE_EMAIL. It is preferred to use `CLOUDFLARE_API_TOKEN`.
+ * - `CLOUDFLARE_EMAIL` - Email address for API key authentication. Used with `CLOUDFLARE_API_KEY`. It is preferred to use `CLOUDFLARE_API_TOKEN`.
+ * - `CLOUDFLARE_API_BASE_URL` - Custom API base URL. Defaults to https://api.cloudflare.com/client/v4
+ * - `CLOUDFLARE_COMPLIANCE_REGION` - Set to "fedramp_high" for FedRAMP High compliance region. This will update the API/AUTH URLs used to make requests to Cloudflare.
+ *
+ * ## Development & Local Testing
+ *
+ * - `WRANGLER_HYPERDRIVE_LOCAL_CONNECTION_STRING_*` - Local database connection strings for Hyperdrive development. The * should be replaced with the Hyperdrive binding name in the Worker.
+ * - `NO_HYPERDRIVE_WARNING` - Suppress Hyperdrive-related warnings during development.
+ * - `WRANGLER_HTTPS_KEY_PATH`/`WRANGLER_HTTPS_CERT_PATH` - Paths to HTTPS private key and certificate files for running the local development server in HTTP mode. Without this Wrangler will generate keys automatically.
+ * - `CLOUDFLARE_LOAD_DEV_VARS_FROM_DOT_ENV` - Load development variables from .env files (default: true).
+ * - `CLOUDFLARE_INCLUDE_PROCESS_ENV` - Include process.env in development variables (default: false).
+ *
+ * ## Logging & Output
+ *
+ * - `WRANGLER_LOG` - Set log level: "debug", "info", "log", "warn", "error".
+ * - `WRANGLER_LOG_PATH` - Directory for debug log files.
+ * - `WRANGLER_LOG_SANITIZE` - Sanitize sensitive data in debug logs (default: true).
+ * - `WRANGLER_OUTPUT_FILE_DIRECTORY` - Directory for ND-JSON output files.
+ * - `WRANGLER_OUTPUT_FILE_PATH` - Specific path for ND-JSON output file.
+ *
+ * ## Build & Deployment Configuration
+ *
+ * - `WRANGLER_BUILD_CONDITIONS` - Comma-separated list of build conditions for esbuild.
+ * - `WRANGLER_BUILD_PLATFORM` - Build platform for esbuild (e.g., "node", "browser").
+ * - `WRANGLER_REGISTRY_PATH` - Path to file-based dev registry folder.
+ * - `WRANGLER_D1_EXTRA_LOCATION_CHOICES` - Additional D1 location choices (internal use).
+ * - `WRANGLER_DOCKER_BIN` - Path to docker binary (default: "docker").
+ *
+ * ## Advanced Configuration
+ *
+ * - `WRANGLER_API_ENVIRONMENT` - Set to "staging" to use staging APIs instead of production.
+ * - `WRANGLER_AUTH_DOMAIN` - Custom auth domain (usually auto-configured).
+ * - `WRANGLER_AUTH_URL` - Custom auth URL (usually auto-configured).
+ * - `WRANGLER_CLIENT_ID` - Custom OAuth client ID (usually auto-configured).
+ * - `WRANGLER_TOKEN_URL` - Custom token URL (usually auto-configured).
+ * - `WRANGLER_REVOKE_URL` - Custom token revocation URL (usually auto-configured).
+ * - `WRANGLER_CF_AUTHORIZATION_TOKEN` - Direct authorization token for API requests.
+ * - `WRANGLER_C3_COMMAND` - Override command used by `wrangler init` (default: "create cloudflare@^2.5.0").
+ * - `WRANGLER_SEND_METRICS` - Enable/disable telemetry data collection.
+ *
+ * Note: CI-specific variables (WRANGLER_CI_*, WORKERS_CI_BRANCH) are for internal use and not documented here.
+ * Docker-related variables (WRANGLER_DOCKER_HOST, DOCKER_HOST) are also available but handled separately.
+ */
 type VariableNames =
 	| "CLOUDFLARE_ACCOUNT_ID"
 	| "CLOUDFLARE_API_BASE_URL"