feat(automation): implement NODE_ENV-based automation mode with fixture server

packages/infrastructure/config/AutomationConfig.ts

@@ -1,16 +1,32 @@
 /**
  * Automation configuration module for environment-based adapter selection.
- * 
+ *
  * This module provides configuration types and loaders for the automation system,
- * allowing switching between different adapters based on environment variables.
+ * allowing switching between different adapters based on NODE_ENV.
+ *
+ * Mapping:
+ * - NODE_ENV=development → BrowserDevToolsAdapter → Fixture Server → CSS Selectors
+ * - NODE_ENV=production  → NutJsAutomationAdapter  → iRacing Window → Image Templates
+ * - NODE_ENV=test        → MockBrowserAutomation   → N/A           → N/A
  */
 
-export type AutomationMode = 'dev' | 'production' | 'mock';
+export type AutomationMode = 'development' | 'production' | 'test';
+
+/**
+ * @deprecated Use AutomationMode instead. Will be removed in future version.
+ */
+export type LegacyAutomationMode = 'dev' | 'production' | 'mock';
+
+export interface FixtureServerConfig {
+  port: number;
+  autoStart: boolean;
+  fixturesPath: string;
+}
 
 export interface AutomationEnvironmentConfig {
   mode: AutomationMode;
   
-  /** Dev mode configuration (Browser DevTools) */
+  /** Development mode configuration (Browser DevTools with fixture server) */
   devTools?: {
     browserWSEndpoint?: string;
     debuggingPort?: number;
@@ -25,6 +41,9 @@ export interface AutomationEnvironmentConfig {
     confidence?: number;
   };
   
+  /** Fixture server configuration for development mode */
+  fixtureServer?: FixtureServerConfig;
+  
   /** Default timeout for automation operations in milliseconds */
   defaultTimeout?: number;
   /** Number of retry attempts for failed operations */
@@ -33,11 +52,41 @@ export interface AutomationEnvironmentConfig {
   screenshotOnError?: boolean;
 }
 
+/**
+ * Get the automation mode based on NODE_ENV.
+ *
+ * Mapping:
+ * - NODE_ENV=production  → 'production'
+ * - NODE_ENV=test        → 'test'
+ * - NODE_ENV=development → 'development' (default)
+ *
+ * For backward compatibility, if AUTOMATION_MODE is explicitly set,
+ * it will be used with a deprecation warning logged to console.
+ *
+ * @returns AutomationMode derived from NODE_ENV
+ */
+export function getAutomationMode(): AutomationMode {
+  const legacyMode = process.env.AUTOMATION_MODE;
+  if (legacyMode && isValidLegacyAutomationMode(legacyMode)) {
+    console.warn(
+      `[DEPRECATED] AUTOMATION_MODE environment variable is deprecated. ` +
+      `Use NODE_ENV instead. Mapping: dev→development, mock→test, production→production`
+    );
+    return mapLegacyMode(legacyMode);
+  }
+  
+  const nodeEnv = process.env.NODE_ENV;
+  if (nodeEnv === 'production') return 'production';
+  if (nodeEnv === 'test') return 'test';
+  return 'development';
+}
+
 /**
  * Load automation configuration from environment variables.
- * 
+ *
  * Environment variables:
- * - AUTOMATION_MODE: 'dev' | 'production' | 'mock' (default: 'mock')
+ * - NODE_ENV: 'development' | 'production' | 'test' (default: 'development')
+ * - AUTOMATION_MODE: (deprecated) 'dev' | 'production' | 'mock'
  * - CHROME_DEBUG_PORT: Chrome debugging port (default: 9222)
  * - CHROME_WS_ENDPOINT: WebSocket endpoint for Chrome DevTools
  * - IRACING_WINDOW_TITLE: Window title for nut.js (default: 'iRacing')
@@ -46,12 +95,14 @@ export interface AutomationEnvironmentConfig {
  * - AUTOMATION_TIMEOUT: Default timeout in ms (default: 30000)
  * - RETRY_ATTEMPTS: Number of retry attempts (default: 3)
  * - SCREENSHOT_ON_ERROR: Capture screenshots on error (default: true)
- * 
+ * - FIXTURE_SERVER_PORT: Port for fixture server (default: 3456)
+ * - FIXTURE_SERVER_AUTO_START: Auto-start fixture server (default: true in development)
+ * - FIXTURE_SERVER_PATH: Path to fixtures (default: './resources/iracing-hosted-sessions')
+ *
  * @returns AutomationEnvironmentConfig with parsed environment values
  */
 export function loadAutomationConfig(): AutomationEnvironmentConfig {
-  const modeEnv = process.env.AUTOMATION_MODE;
-  const mode: AutomationMode = isValidAutomationMode(modeEnv) ? modeEnv : 'mock';
+  const mode = getAutomationMode();
   
   return {
     mode,
@@ -66,6 +117,11 @@ export function loadAutomationConfig(): AutomationEnvironmentConfig {
       templatePath: process.env.TEMPLATE_PATH || './resources/templates',
       confidence: parseFloatSafe(process.env.OCR_CONFIDENCE, 0.9),
     },
+    fixtureServer: {
+      port: parseIntSafe(process.env.FIXTURE_SERVER_PORT, 3456),
+      autoStart: process.env.FIXTURE_SERVER_AUTO_START !== 'false' && mode === 'development',
+      fixturesPath: process.env.FIXTURE_SERVER_PATH || './resources/iracing-hosted-sessions',
+    },
     defaultTimeout: parseIntSafe(process.env.AUTOMATION_TIMEOUT, 30000),
     retryAttempts: parseIntSafe(process.env.RETRY_ATTEMPTS, 3),
     screenshotOnError: process.env.SCREENSHOT_ON_ERROR !== 'false',
@@ -76,9 +132,27 @@ export function loadAutomationConfig(): AutomationEnvironmentConfig {
  * Type guard to validate automation mode string.
  */
 function isValidAutomationMode(value: string | undefined): value is AutomationMode {
+  return value === 'development' || value === 'production' || value === 'test';
+}
+
+/**
+ * Type guard to validate legacy automation mode string.
+ */
+function isValidLegacyAutomationMode(value: string | undefined): value is LegacyAutomationMode {
   return value === 'dev' || value === 'production' || value === 'mock';
 }
 
+/**
+ * Map legacy automation mode to new mode.
+ */
+function mapLegacyMode(legacy: LegacyAutomationMode): AutomationMode {
+  switch (legacy) {
+    case 'dev': return 'development';
+    case 'mock': return 'test';
+    case 'production': return 'production';
+  }
+}
+
 /**
  * Safely parse an integer with a default fallback.
  */

packages/infrastructure/config/index.ts

@@ -5,5 +5,7 @@
 export {
   AutomationMode,
   AutomationEnvironmentConfig,
+  FixtureServerConfig,
   loadAutomationConfig,
+  getAutomationMode,
 } from './AutomationConfig';