feat: add automatic .env file loading to run and list commands

Users can now use environment variables in scenario files without manual
setup. By default, .env files are loaded before scenario execution,
following common practices in testing and development workflows.

- Add loadEnvironment() utility for .env file loading via @std/dotenv
- Load .env automatically before config file reading in run/list commands
- Add --env <file> option to specify custom .env file path
- Add --no-env option to skip automatic .env loading
- Update usage documentation with environment variable examples

Environment variables loaded in main thread are inherited by Worker threads,
making them available to all scenario executions.

Author: lambdalisue

assets/usage-list.txt

@@ -14,6 +14,8 @@ Options:
                              Supports ! prefix for negation
   --json                     Output in JSON format
   --config <path>            Path to config file (deno.json/deno.jsonc)
+  --env <file>               Load environment variables from file (default: .env)
+  --no-env                   Skip loading .env file
   -r, --reload               Reload dependencies before running
 
 Selector Format:
@@ -66,6 +68,12 @@ Examples:
   probitas list --json                          Output as JSON
   probitas list --reload                        Reload dependencies before listing
 
+  # Environment variables
+  probitas list                                 Load .env file automatically
+  probitas list --env .env.test                 Load custom env file
+  probitas list --no-env                        Skip loading .env file
+
 Note: Uses patterns from config file or defaults to "**/*.probitas.ts"
+      .env file is automatically loaded before scenario listing (use --no-env to skip)
 
 Documentation: https://jsr-probitas.github.io/documents/

assets/usage-run.txt

@@ -22,6 +22,8 @@ Options:
   --max-failures <n>        Stop after N failures
   -f, --fail-fast           Stop on first failure (alias for --max-failures=1)
   --config <path>           Path to config file (deno.json/deno.jsonc)
+  --env <file>              Load environment variables from file (default: .env)
+  --no-env                  Skip loading .env file
   -r, --reload              Reload dependencies before running
   -q, --quiet               Quiet output (errors only)
   -v, --verbose             Verbose output
@@ -96,7 +98,13 @@ Examples:
   probitas run -d                           Debug output
   probitas run --debug                      Debug output (same as -d)
 
+  # Environment variables
+  probitas run                              Load .env file automatically
+  probitas run --env .env.test              Load custom env file
+  probitas run --no-env                     Skip loading .env file
+
 Environment Variables:
   NO_COLOR         Disable colored output
+  .env File:       Automatically loaded before scenario execution (use --no-env to skip)
 
 Documentation: https://jsr-probitas.github.io/documents/

deno.json

@@ -43,6 +43,7 @@
     "@std/assert": "jsr:@std/assert@^1.0.16",
     "@std/cli": "jsr:@std/cli@^1.0.24",
     "@std/collections": "jsr:@std/collections@^1.1.3",
+    "@std/dotenv": "jsr:@std/dotenv@^0.225.4",
     "@std/fs": "jsr:@std/fs@^1.0.20",
     "@std/jsonc": "jsr:@std/jsonc@^1.0.2",
     "@std/path": "jsr:@std/path@^1.1.3",

deno.lock

@@ -14,7 +14,7 @@ import { applySelectors } from "@probitas/core/selector";
 import { EXIT_CODE } from "../constants.ts";
 import { findProbitasConfigFile, loadConfig } from "../config.ts";
 import { createDiscoveryProgress, writeStatus } from "../progress.ts";
-import { readAsset } from "../utils.ts";
+import { loadEnvironment, readAsset } from "../utils.ts";
 
 const logger = getLogger("probitas", "cli", "list");
 
@@ -34,8 +34,16 @@ export async function listCommand(
   try {
     // Parse command-line arguments
     const parsed = parseArgs(args, {
-      string: ["config", "include", "exclude", "selector"],
-      boolean: ["help", "json", "reload", "quiet", "verbose", "debug"],
+      string: ["config", "include", "exclude", "selector", "env"],
+      boolean: [
+        "help",
+        "json",
+        "no-env",
+        "reload",
+        "quiet",
+        "verbose",
+        "debug",
+      ],
       collect: ["include", "exclude", "selector"],
       alias: {
         h: "help",
@@ -85,6 +93,13 @@ export async function listCommand(
       // Silently ignore logging configuration errors (e.g., in test environments)
     }
 
+    // Load environment variables before loading configuration
+    // This allows config files to reference environment variables
+    await loadEnvironment(cwd, {
+      noEnv: parsed["no-env"],
+      envFile: parsed.env,
+    });
+
     // Load configuration
     const configPath = parsed.config ??
       await findProbitasConfigFile(cwd, { parentLookup: true });

src/commands/list.ts

@@ -21,6 +21,7 @@ import {
   toScenarioMetadata,
 } from "@probitas/runner";
 import {
+  loadEnvironment,
   parsePositiveInteger,
   parseTimeout,
   readAsset,
@@ -56,11 +57,13 @@ export async function runCommand(
         "exclude",
         "selector",
         "timeout",
+        "env",
       ],
       boolean: [
         "help",
         "no-color",
         "no-timeout",
+        "no-env",
         "reload",
         "quiet",
         "verbose",
@@ -119,6 +122,13 @@ export async function runCommand(
       // Silently ignore logging configuration errors (e.g., in test environments)
     }
 
+    // Load environment variables before loading configuration
+    // This allows config files to reference environment variables
+    await loadEnvironment(cwd, {
+      noEnv: parsed["no-env"],
+      envFile: parsed.env,
+    });
+
     // Load configuration
     const configPath = parsed.config ??
       await findProbitasConfigFile(cwd, { parentLookup: true });

src/commands/run.ts

@@ -9,6 +9,9 @@ import { getLogger } from "@probitas/logger";
 import { JSONReporter, ListReporter } from "@probitas/reporter";
 import type { Reporter } from "@probitas/runner";
 import type { ReporterOptions } from "@probitas/reporter";
+import { load } from "@std/dotenv";
+import { exists } from "@std/fs";
+import { resolve } from "@std/path";
 
 const logger = getLogger("probitas", "cli", "utils");
 
@@ -255,3 +258,69 @@ export async function getVersionInfo(): Promise<VersionInfo | undefined> {
     return undefined;
   }
 }
+
+/**
+ * Load environment variables from a .env file
+ *
+ * @param cwd - Current working directory
+ * @param options - Environment loading options
+ * @returns void
+ *
+ * @example
+ * ```ts
+ * import { loadEnvironment } from "./utils.ts";
+ *
+ * const cwd = Deno.cwd();
+ *
+ * // Load default .env file
+ * await loadEnvironment(cwd);
+ *
+ * // Skip loading .env
+ * await loadEnvironment(cwd, { noEnv: true });
+ *
+ * // Load custom .env file
+ * await loadEnvironment(cwd, { envFile: ".env.test" });
+ * ```
+ */
+export async function loadEnvironment(
+  cwd: string,
+  options?: {
+    /** Skip loading .env file */
+    noEnv?: boolean;
+    /** Custom .env file path (relative to cwd or absolute) */
+    envFile?: string;
+  },
+): Promise<void> {
+  const { noEnv = false, envFile } = options ?? {};
+
+  // Skip if --no-env is specified
+  if (noEnv) {
+    logger.debug("Environment loading disabled via --no-env");
+    return;
+  }
+
+  // Determine which file to load
+  const targetFile = envFile ?? ".env";
+  const targetPath = resolve(cwd, targetFile);
+
+  // Check if file exists
+  if (!(await exists(targetPath))) {
+    logger.debug("Environment file not found", { path: targetPath });
+    return;
+  }
+
+  // Load environment variables
+  try {
+    const env = await load({ envPath: targetPath, export: true });
+    logger.debug("Environment loaded", {
+      path: targetPath,
+      keys: Object.keys(env),
+    });
+  } catch (err: unknown) {
+    // Log error but don't fail - missing .env is acceptable
+    logger.debug("Failed to load environment file", {
+      path: targetPath,
+      error: err,
+    });
+  }
+}