feat: add environment configuration and documentation

- Add .env.example template with required environment variables
- Create ENV_SETUP.md documentation for environment configuration
- Implement env-config.ts utility for centralized environment management
- Update processor edge cases tests to handle new configuration
- Update dependencies to support environment configuration

Author: AdamManuel-dev

.env.example

@@ -0,0 +1,50 @@
+# Auto Image Diff - Environment Configuration
+# Copy this file to .env and update with your values
+
+# Node Environment
+NODE_ENV=development
+
+# Logging Configuration
+LOG_LEVEL=info
+LOG_FORMAT=json
+
+# Performance Settings
+MAX_WORKERS=4
+BATCH_SIZE=10
+MEMORY_LIMIT=4096
+
+# Image Processing Settings
+IMAGE_QUALITY=85
+MAX_IMAGE_SIZE=10485760
+DIFF_THRESHOLD=0.1
+
+# Output Configuration
+OUTPUT_DIR=./output
+ENABLE_HTML_REPORTS=true
+ENABLE_JSON_REPORTS=true
+
+# Cache Settings
+ENABLE_CACHE=true
+CACHE_DIR=./cache
+CACHE_TTL=86400
+
+# Debug Mode
+DEBUG_MODE=false
+VERBOSE_OUTPUT=false
+
+# API/Service URLs (for future integrations)
+# API_BASE_URL=https://api.example.com
+# API_KEY=your-api-key-here
+
+# AWS S3 (for future cloud storage)
+# AWS_REGION=us-east-1
+# AWS_BUCKET=auto-image-diff-storage
+# AWS_ACCESS_KEY_ID=your-access-key
+# AWS_SECRET_ACCESS_KEY=your-secret-key
+
+# Database (for future metadata storage)
+# DATABASE_URL=postgresql://user:password@localhost:5432/auto_image_diff
+
+# Monitoring (for future telemetry)
+# SENTRY_DSN=https://your-sentry-dsn
+# ENABLE_TELEMETRY=false

docs/ENV_SETUP.md

@@ -0,0 +1,123 @@
+# Environment Configuration Guide
+
+This guide explains how to set up and configure environment variables for the Auto Image Diff tool.
+
+## Quick Start
+
+1. Copy the example environment file:
+
+   ```bash
+   cp .env.example .env
+   ```
+
+2. Edit `.env` with your preferred values (the defaults work well for most cases)
+
+3. The application will automatically load these settings on startup
+
+## Environment Variables
+
+### Node Environment
+
+- `NODE_ENV` - Application environment (`development`, `production`, `test`)
+  - Default: `development`
+
+### Logging Configuration
+
+- `LOG_LEVEL` - Minimum log level to display (`debug`, `info`, `warn`, `error`)
+  - Default: `info`
+- `LOG_FORMAT` - Log output format (`json`, `text`)
+  - Default: `json`
+
+### Performance Settings
+
+- `MAX_WORKERS` - Maximum number of parallel workers (1-32)
+  - Default: `4`
+- `BATCH_SIZE` - Number of images to process in each batch (1-100)
+  - Default: `10`
+- `MEMORY_LIMIT` - Memory limit in MB (512-16384)
+  - Default: `4096`
+
+### Image Processing Settings
+
+- `IMAGE_QUALITY` - JPEG quality for output images (1-100)
+  - Default: `85`
+- `MAX_IMAGE_SIZE` - Maximum image file size in bytes
+  - Default: `10485760` (10MB)
+- `DIFF_THRESHOLD` - Pixel difference threshold (0-1)
+  - Default: `0.1`
+
+### Output Configuration
+
+- `OUTPUT_DIR` - Directory for output files
+  - Default: `./output`
+- `ENABLE_HTML_REPORTS` - Generate HTML reports (`true`, `false`)
+  - Default: `true`
+- `ENABLE_JSON_REPORTS` - Generate JSON reports (`true`, `false`)
+  - Default: `true`
+
+### Cache Settings
+
+- `ENABLE_CACHE` - Enable caching (`true`, `false`)
+  - Default: `true`
+- `CACHE_DIR` - Directory for cache files
+  - Default: `./cache`
+- `CACHE_TTL` - Cache time-to-live in seconds
+  - Default: `86400` (24 hours)
+
+### Debug Mode
+
+- `DEBUG_MODE` - Enable debug mode (`true`, `false`)
+  - Default: `false`
+- `VERBOSE_OUTPUT` - Enable verbose output (`true`, `false`)
+  - Default: `false`
+
+## Using Environment Variables in Code
+
+The environment configuration is automatically loaded and validated. To use it in your code:
+
+```typescript
+import { getConfig, get } from "./lib/env-config";
+
+// Get the entire config object
+const config = getConfig();
+console.log(config.maxWorkers);
+
+// Get a specific value
+const logLevel = get("logLevel");
+```
+
+## Validation
+
+The environment configuration includes built-in validation:
+
+- Numeric values are checked for valid ranges
+- Required values are verified
+- Invalid configurations will throw an error on startup
+
+## Security Notes
+
+- **Never commit `.env` files** to version control
+- The `.env` file is automatically excluded via `.gitignore`
+- Use `.env.example` as a template for other developers
+- Store sensitive values (API keys, passwords) securely
+- Consider using environment-specific files (`.env.production`, `.env.test`)
+
+## Troubleshooting
+
+### Environment variables not loading
+
+- Ensure `.env` file exists in the project root
+- Check file permissions
+- Verify no syntax errors in `.env` file
+
+### Validation errors
+
+- Check that numeric values are within allowed ranges
+- Ensure required variables are set
+- Review error messages for specific issues
+
+### Performance issues
+
+- Adjust `MAX_WORKERS` based on your CPU cores
+- Increase `MEMORY_LIMIT` for large images
+- Enable caching for repeated operations

package-lock.json

@@ -83,6 +83,7 @@
   },
   "dependencies": {
     "commander": "^14.0.0",
+    "dotenv": "^17.2.1",
     "gm": "^1.25.1",
     "imagemagick": "^0.1.3",
     "pixelmatch": "^7.1.0",

package.json

@@ -1,3 +1,4 @@
+/* eslint-disable no-console */
 /**
  * @fileoverview Processor edge case tests
  * @lastmodified 2025-08-01T06:30:00Z

src/__tests__/processor-edge-cases.test.ts

@@ -0,0 +1,150 @@
+/**
+ * @fileoverview Environment configuration validation and loading
+ * @lastmodified 2025-08-02T00:00:00Z
+ *
+ * Features: Environment validation, type-safe config, default values
+ * Main APIs: loadConfig(), validateConfig(), getConfig()
+ * Constraints: Requires valid .env file or defaults
+ * Patterns: Singleton pattern, validation on load
+ */
+
+import * as dotenv from "dotenv";
+
+interface Config {
+  // Node Environment
+  nodeEnv: "development" | "production" | "test";
+
+  // Logging
+  logLevel: "debug" | "info" | "warn" | "error";
+  logFormat: "json" | "text";
+
+  // Performance
+  maxWorkers: number;
+  batchSize: number;
+  memoryLimit: number;
+
+  // Image Processing
+  imageQuality: number;
+  maxImageSize: number;
+  diffThreshold: number;
+
+  // Output
+  outputDir: string;
+  enableHtmlReports: boolean;
+  enableJsonReports: boolean;
+
+  // Cache
+  enableCache: boolean;
+  cacheDir: string;
+  cacheTTL: number;
+
+  // Debug
+  debugMode: boolean;
+  verboseOutput: boolean;
+}
+
+class EnvConfig {
+  private static instance: EnvConfig;
+  private config: Config | null = null;
+
+  private constructor() {}
+
+  static getInstance(): EnvConfig {
+    if (!EnvConfig.instance) {
+      EnvConfig.instance = new EnvConfig();
+    }
+    return EnvConfig.instance;
+  }
+
+  loadConfig(): Config {
+    if (this.config) {
+      return this.config;
+    }
+
+    // Load .env file using dotenv
+    dotenv.config();
+
+    // Build config from environment variables with defaults
+    this.config = {
+      nodeEnv: (process.env.NODE_ENV as Config["nodeEnv"]) || "development",
+      logLevel: (process.env.LOG_LEVEL as Config["logLevel"]) || "info",
+      logFormat: (process.env.LOG_FORMAT as Config["logFormat"]) || "json",
+      maxWorkers: parseInt(process.env.MAX_WORKERS || "4", 10),
+      batchSize: parseInt(process.env.BATCH_SIZE || "10", 10),
+      memoryLimit: parseInt(process.env.MEMORY_LIMIT || "4096", 10),
+      imageQuality: parseInt(process.env.IMAGE_QUALITY || "85", 10),
+      maxImageSize: parseInt(process.env.MAX_IMAGE_SIZE || "10485760", 10),
+      diffThreshold: parseFloat(process.env.DIFF_THRESHOLD || "0.1"),
+      outputDir: process.env.OUTPUT_DIR || "./output",
+      enableHtmlReports: process.env.ENABLE_HTML_REPORTS !== "false",
+      enableJsonReports: process.env.ENABLE_JSON_REPORTS !== "false",
+      enableCache: process.env.ENABLE_CACHE !== "false",
+      cacheDir: process.env.CACHE_DIR || "./cache",
+      cacheTTL: parseInt(process.env.CACHE_TTL || "86400", 10),
+      debugMode: process.env.DEBUG_MODE === "true",
+      verboseOutput: process.env.VERBOSE_OUTPUT === "true",
+    };
+
+    this.validateConfig(this.config);
+    return this.config;
+  }
+
+  private validateConfig(config: Config): void {
+    const errors: string[] = [];
+
+    // Validate numeric ranges
+    if (config.maxWorkers < 1 || config.maxWorkers > 32) {
+      errors.push("MAX_WORKERS must be between 1 and 32");
+    }
+
+    if (config.batchSize < 1 || config.batchSize > 100) {
+      errors.push("BATCH_SIZE must be between 1 and 100");
+    }
+
+    if (config.memoryLimit < 512 || config.memoryLimit > 16384) {
+      errors.push("MEMORY_LIMIT must be between 512 and 16384 MB");
+    }
+
+    if (config.imageQuality < 1 || config.imageQuality > 100) {
+      errors.push("IMAGE_QUALITY must be between 1 and 100");
+    }
+
+    if (config.diffThreshold < 0 || config.diffThreshold > 1) {
+      errors.push("DIFF_THRESHOLD must be between 0 and 1");
+    }
+
+    // Validate paths
+    if (!config.outputDir) {
+      errors.push("OUTPUT_DIR must not be empty");
+    }
+
+    if (!config.cacheDir) {
+      errors.push("CACHE_DIR must not be empty");
+    }
+
+    if (errors.length > 0) {
+      throw new Error(`Environment configuration errors:\n${errors.join("\n")}`);
+    }
+  }
+
+  getConfig(): Config {
+    if (!this.config) {
+      this.loadConfig();
+    }
+    return this.config as Config;
+  }
+
+  // Helper method to get single config value
+  get<K extends keyof Config>(key: K): Config[K] {
+    return this.getConfig()[key];
+  }
+}
+
+// Export singleton instance
+export const envConfig = EnvConfig.getInstance();
+export type { Config };
+
+// Export convenience functions
+export const loadConfig = (): Config => envConfig.loadConfig();
+export const getConfig = (): Config => envConfig.getConfig();
+export const get = <K extends keyof Config>(key: K): Config[K] => envConfig.get(key);