gridpilot.gg/packages/infrastructure/config/AutomationConfig.ts

/**
 * 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 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 = '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;
  
  /** Development mode configuration (Browser DevTools with fixture server) */
  devTools?: {
    browserWSEndpoint?: string;
    debuggingPort?: number;
  };
  
  /** Production mode configuration (nut.js) */
  nutJs?: {
    mouseSpeed?: number;
    keyboardDelay?: number;
    windowTitle?: string;
    templatePath?: string;
    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 */
  retryAttempts?: number;
  /** Whether to capture screenshots on error */
  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:
 * - 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')
 * - TEMPLATE_PATH: Path to template images (default: './resources/templates')
 * - OCR_CONFIDENCE: OCR confidence threshold (default: 0.9)
 * - 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 mode = getAutomationMode();
  
  return {
    mode,
    devTools: {
      debuggingPort: parseIntSafe(process.env.CHROME_DEBUG_PORT, 9222),
      browserWSEndpoint: process.env.CHROME_WS_ENDPOINT,
    },
    nutJs: {
      mouseSpeed: parseIntSafe(process.env.NUTJS_MOUSE_SPEED, 1000),
      keyboardDelay: parseIntSafe(process.env.NUTJS_KEYBOARD_DELAY, 50),
      windowTitle: process.env.IRACING_WINDOW_TITLE || 'iRacing',
      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',
  };
}

/**
 * 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.
 */
function parseIntSafe(value: string | undefined, defaultValue: number): number {
  if (value === undefined || value === '') {
    return defaultValue;
  }
  const parsed = parseInt(value, 10);
  return isNaN(parsed) ? defaultValue : parsed;
}

/**
 * Safely parse a float with a default fallback.
 */
function parseFloatSafe(value: string | undefined, defaultValue: number): number {
  if (value === undefined || value === '') {
    return defaultValue;
  }
  const parsed = parseFloat(value);
  return isNaN(parsed) ? defaultValue : parsed;
}