wilfredwake 1.0.0

package/src/shared/colors.js

@@ -0,0 +1,154 @@
+/**
+ * ╔═══════════════════════════════════════════════════════════════╗
+ * ║                      COLORS & THEMES MODULE                   ║
+ * ║     Provides consistent color scheme for CLI output           ║
+ * ║     Uses chalk for terminal color support                    ║
+ * ╚═══════════════════════════════════════════════════════════════╝
+ */
+
+import chalk from 'chalk';
+
+/**
+ * Color scheme definitions
+ * Each color is assigned a semantic meaning for consistent UX
+ */
+export const colors = {
+  // ═══════════════════════════════════════════════════════════════
+  // STATUS INDICATORS - Service states with visual distinction
+  // ═══════════════════════════════════════════════════════════════
+  status: {
+    // New architecture states
+    live: chalk.greenBright,            // ✓ Service is responsive and healthy
+    dead: chalk.gray,                   // ⚫ Service is not responding/dormant
+    waking: chalk.yellowBright,         // ⟳ Service is responding slowly
+    failed: chalk.redBright,            // ✗ Service failed to respond
+    unknown: chalk.magentaBright,       // ? Unknown state
+    
+    // Legacy states (for backwards compatibility)
+    ready: chalk.greenBright,           // ✓ Service is running and healthy
+    sleeping: chalk.gray,               // ⚫ Service is in sleep/cold state
+    pending: chalk.blueBright,          // ⏳ Service is pending action
+    error: chalk.red,                   // ⚠️ Error occurred
+  },
+
+  // ═══════════════════════════════════════════════════════════════
+  // ACTION MESSAGES - Operation feedback
+  // ═══════════════════════════════════════════════════════════════
+  action: {
+    success: chalk.greenBright,         // Operation completed successfully
+    warning: chalk.yellowBright,        // Warning/caution message
+    info: chalk.cyanBright,             // Informational message
+    debug: chalk.gray,                  // Debug/verbose output
+    prompt: chalk.blueBright,           // User input prompt
+  },
+
+  // ═══════════════════════════════════════════════════════════════
+  // EMPHASIS - UI elements and emphasis
+  // ═══════════════════════════════════════════════════════════════
+  emphasis: {
+    primary: chalk.cyan,                // Primary/main heading
+    secondary: chalk.magenta,           // Secondary heading
+    accent: chalk.yellow,               // Accent elements
+    muted: chalk.gray,                  // Muted/secondary text
+    highlight: chalk.inverse,           // Highlighted text
+  },
+
+  // ═══════════════════════════════════════════════════════════════
+  // SPECIAL MARKERS - Icons and visual elements
+  // ═══════════════════════════════════════════════════════════════
+  markers: {
+    success: chalk.greenBright('✓'),
+    error: chalk.redBright('✗'),
+    warning: chalk.yellowBright('⚠'),
+    info: chalk.cyanBright('ℹ'),
+    arrow: chalk.dim('→'),
+    bullet: chalk.dim('•'),
+    spinner: ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'],
+  },
+};
+
+/**
+ * Formatting utilities for structured output
+ */
+export const format = {
+  /**
+   * Format a service status line with color coding
+   * @param {string} serviceName - Name of the service
+   * @param {string} status - Current status (ready, sleeping, waking, etc)
+   * @param {string} message - Optional message to display
+   * @returns {string} Formatted status line
+   */
+  serviceStatus(serviceName, status, message = '') {
+    const statusColor = colors.status[status] || colors.status.unknown;
+    const statusText = statusColor(status.toUpperCase().padEnd(10));
+    const msgText = message ? ` ${colors.emphasis.muted(`(${message})`)}` : '';
+    return `  ${statusText} ${chalk.cyan(serviceName)}${msgText}`;
+  },
+
+  /**
+   * Format a table header row
+   * @param {string[]} columns - Column names
+   * @returns {string} Formatted header
+   */
+  tableHeader(columns) {
+    return chalk.inverse(
+      ' ' + columns.map(col => col.padEnd(20)).join(' ') + ' '
+    );
+  },
+
+  /**
+   * Format a table row
+   * @param {string[]} cells - Cell values
+   * @returns {string} Formatted row
+   */
+  tableRow(cells) {
+    return '  ' + cells.map(cell => cell.padEnd(20)).join(' ');
+  },
+
+  /**
+   * Format a section header
+   * @param {string} title - Section title
+   * @returns {string} Formatted header
+   */
+  section(title) {
+    return chalk.cyanBright.bold(`\n▶ ${title}\n`);
+  },
+
+  /**
+   * Format a success message
+   * @param {string} message - Message text
+   * @returns {string} Formatted message
+   */
+  success(message) {
+    return `${colors.markers.success} ${chalk.greenBright(message)}`;
+  },
+
+  /**
+   * Format an error message
+   * @param {string} message - Message text
+   * @returns {string} Formatted message
+   */
+  error(message) {
+    return `${colors.markers.error} ${chalk.redBright(message)}`;
+  },
+
+  /**
+   * Format an info message
+   * @param {string} message - Message text
+   * @returns {string} Formatted message
+   */
+  info(message) {
+    return `${colors.markers.info} ${chalk.cyanBright(message)}`;
+  },
+
+  /**
+   * Format a warning message
+   * @param {string} message - Message text
+   * @returns {string} Formatted message
+   */
+  warning(message) {
+    return `${colors.markers.warning} ${chalk.yellowBright(message)}`;
+  },
+};
+
+export default { colors, format };

package/src/shared/logger.js

@@ -0,0 +1,224 @@
+/**
+ * ╔═══════════════════════════════════════════════════════════════╗
+ * ║                    LOGGER & UTILITIES MODULE                  ║
+ * ║           Provides logging and utility functions               ║
+ * ╚═══════════════════════════════════════════════════════════════╝
+ */
+
+import chalk from 'chalk';
+import { colors, format } from './colors.js';
+
+/**
+ * Logger class for consistent output formatting
+ * Provides methods for different log levels with color coding
+ */
+export class Logger {
+  constructor(verbose = false) {
+    this.verbose = verbose;
+    this.spinnerState = 0;
+  }
+
+  /**
+   * Log a success message
+   * @param {string} message - Message to log
+   */
+  success(message) {
+    console.log(format.success(message));
+  }
+
+  /**
+   * Log an error message
+   * @param {string} message - Message to log
+   */
+  error(message) {
+    console.error(format.error(message));
+  }
+
+  /**
+   * Log an info message
+   * @param {string} message - Message to log
+   */
+  info(message) {
+    console.log(format.info(message));
+  }
+
+  /**
+   * Log a warning message
+   * @param {string} message - Message to log
+   */
+  warn(message) {
+    console.warn(format.warning(message));
+  }
+
+  /**
+   * Log a debug message (only if verbose mode enabled)
+   * @param {string} message - Message to log
+   */
+  debug(message) {
+    if (this.verbose) {
+      console.log(colors.emphasis.muted(`[DEBUG] ${message}`));
+    }
+  }
+
+  /**
+   * Log a section header
+   * @param {string} title - Section title
+   */
+  section(title) {
+    console.log(format.section(title));
+  }
+
+  /**
+   * Start a spinner animation
+   * @param {string} message - Message while spinning
+   * @returns {Function} Function to stop spinner
+   */
+  spinner(message) {
+    const frames = colors.markers.spinner;
+    let index = 0;
+
+    const interval = setInterval(() => {
+      process.stdout.write(
+        `\r${chalk.blueBright(frames[index])} ${message}`
+      );
+      index = (index + 1) % frames.length;
+    }, 100);
+
+    return () => {
+      clearInterval(interval);
+      process.stdout.write('\r'); // Clear line
+    };
+  }
+}
+
+/**
+ * Utility functions for common operations
+ */
+export const utils = {
+  /**
+   * Wait for a specified number of milliseconds
+   * @param {number} ms - Milliseconds to wait
+   * @returns {Promise<void>}
+   */
+  async wait(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+  },
+
+  /**
+   * Retry an async operation with exponential backoff
+   * @param {Function} fn - Async function to retry
+   * @param {number} maxAttempts - Maximum retry attempts
+   * @param {number} baseDelay - Base delay in milliseconds
+   * @returns {Promise<any>} Result from successful attempt
+   */
+  async retry(fn, maxAttempts = 5, baseDelay = 1000) {
+    let lastError;
+
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+      try {
+        return await fn();
+      } catch (error) {
+        lastError = error;
+        if (attempt < maxAttempts) {
+          const delay = baseDelay * Math.pow(2, attempt - 1);
+          await this.wait(delay);
+        }
+      }
+    }
+
+    throw lastError;
+  },
+
+  /**
+   * Check if a URL is reachable
+   * @param {string} url - URL to check
+   * @param {number} timeout - Timeout in milliseconds
+   * @returns {Promise<boolean>} True if reachable
+   */
+  async isUrlReachable(url, timeout = 5000) {
+    try {
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), timeout);
+
+      const response = await fetch(url, {
+        method: 'GET',
+        signal: controller.signal,
+      });
+
+      clearTimeout(timeoutId);
+      return response.ok;
+    } catch (error) {
+      return false;
+    }
+  },
+
+  /**
+   * Format milliseconds to human-readable duration
+   * @param {number} ms - Milliseconds
+   * @returns {string} Formatted duration (e.g., "2.5s", "1m 30s")
+   */
+  formatDuration(ms) {
+    if (ms < 1000) return `${Math.round(ms)}ms`;
+    if (ms < 60000) return `${(ms / 1000).toFixed(1)}s`;
+
+    const minutes = Math.floor(ms / 60000);
+    const seconds = Math.round((ms % 60000) / 1000);
+    return `${minutes}m ${seconds}s`;
+  },
+
+  /**
+   * Parse duration string to milliseconds
+   * @param {string} duration - Duration string (e.g., "5m", "30s")
+   * @returns {number} Milliseconds
+   */
+  parseDuration(duration) {
+    const match = duration.match(/^(\d+)([smh])$/);
+    if (!match) throw new Error(`Invalid duration format: ${duration}`);
+
+    const [, amount, unit] = match;
+    const multipliers = { s: 1000, m: 60000, h: 3600000 };
+    return parseInt(amount, 10) * multipliers[unit];
+  },
+
+  /**
+   * Deep merge objects
+   * @param {Object} target - Target object
+   * @param {Object} source - Source object to merge
+   * @returns {Object} Merged object
+   */
+  deepMerge(target, source) {
+    const result = { ...target };
+
+    for (const key in source) {
+      if (source.hasOwnProperty(key)) {
+        if (
+          typeof source[key] === 'object' &&
+          source[key] !== null &&
+          !Array.isArray(source[key])
+        ) {
+          result[key] = this.deepMerge(result[key] || {}, source[key]);
+        } else {
+          result[key] = source[key];
+        }
+      }
+    }
+
+    return result;
+  },
+
+  /**
+   * Validate URL format
+   * @param {string} url - URL to validate
+   * @returns {boolean} True if valid URL
+   */
+  isValidUrl(url) {
+    try {
+      new URL(url);
+      return true;
+    } catch {
+      return false;
+    }
+  },
+};
+
+export default { Logger, utils };

package/tests/cli.test.js

@@ -0,0 +1,328 @@
+/**
+ * ╔═══════════════════════════════════════════════════════════════╗
+ * ║                    TEST FILE EXAMPLES                        ║
+ * ║     Unit and integration tests for wilfredwake                ║
+ * ╚═══════════════════════════════════════════════════════════════╝
+ *
+ * Run tests with: npm test
+ * Watch mode: npm run test:watch
+ */
+
+import test from 'node:test';
+import assert from 'node:assert';
+import ServiceRegistry from '../src/orchestrator/registry.js';
+import { Orchestrator, ServiceState } from '../src/orchestrator/orchestrator.js';
+
+/**
+ * Test Suite: Service Registry
+ */
+test('ServiceRegistry - Load and validate YAML', async (t) => {
+  const registry = new ServiceRegistry();
+
+  const yaml = `
+services:
+  dev:
+    auth:
+      url: https://auth.test
+      health: /health
+      wake: /wake
+      dependsOn: []
+    payment:
+      url: https://payment.test
+      health: /health
+      wake: /wake
+      dependsOn: [auth]
+`;
+
+  await registry.loadFromString(yaml, 'yaml');
+  const services = registry.getServices('dev');
+
+  assert.equal(services.length, 2, 'Should load 2 services');
+  assert.equal(services[0].name, 'auth', 'First service should be auth');
+});
+
+test('ServiceRegistry - Resolve wake order with dependencies', async (t) => {
+  const registry = new ServiceRegistry();
+
+  const yaml = `
+services:
+  dev:
+    auth:
+      url: https://auth.test
+      health: /health
+      wake: /wake
+      dependsOn: []
+    payment:
+      url: https://payment.test
+      health: /health
+      wake: /wake
+      dependsOn: [auth]
+    consumer:
+      url: https://consumer.test
+      health: /health
+      wake: /wake
+      dependsOn: [payment]
+`;
+
+  await registry.loadFromString(yaml, 'yaml');
+  const order = registry.resolveWakeOrder('all', 'dev');
+
+  assert.equal(order.length, 3, 'Should resolve 3 services');
+  assert.equal(order[0].name, 'auth', 'Auth should be first');
+  assert.equal(order[1].name, 'payment', 'Payment should be second');
+  assert.equal(order[2].name, 'consumer', 'Consumer should be third');
+});
+
+test('ServiceRegistry - Detect circular dependencies', async (t) => {
+  const registry = new ServiceRegistry();
+
+  const yaml = `
+services:
+  dev:
+    auth:
+      url: https://auth.test
+      health: /health
+      wake: /wake
+      dependsOn: [payment]
+    payment:
+      url: https://payment.test
+      health: /health
+      wake: /wake
+      dependsOn: [auth]
+`;
+
+  await registry.loadFromString(yaml, 'yaml');
+
+  assert.throws(
+    () => registry.resolveWakeOrder('all', 'dev'),
+    /Circular dependency/,
+    'Should detect circular dependency'
+  );
+});
+
+test('ServiceRegistry - Get service by name', async (t) => {
+  const registry = new ServiceRegistry();
+
+  const yaml = `
+services:
+  dev:
+    auth:
+      url: https://auth.test
+      health: /health
+      wake: /wake
+      dependsOn: []
+`;
+
+  await registry.loadFromString(yaml, 'yaml');
+  const service = registry.getService('auth', 'dev');
+
+  assert.ok(service, 'Should find service');
+  assert.equal(service.name, 'auth', 'Service name should match');
+  assert.equal(service.url, 'https://auth.test', 'Service URL should match');
+});
+
+test('ServiceRegistry - Get registry statistics', async (t) => {
+  const registry = new ServiceRegistry();
+
+  const yaml = `
+services:
+  dev:
+    auth:
+      url: https://auth.test
+      health: /health
+      wake: /wake
+      dependsOn: []
+    payment:
+      url: https://payment.test
+      health: /health
+      wake: /wake
+      dependsOn: [auth]
+  staging:
+    auth:
+      url: https://auth-staging.test
+      health: /health
+      wake: /wake
+      dependsOn: []
+`;
+
+  await registry.loadFromString(yaml, 'yaml');
+  const stats = registry.getStats();
+
+  assert.equal(stats.totalServices, 3, 'Should count 3 total services');
+  assert.equal(stats.environments.length, 2, 'Should have 2 environments');
+});
+
+/**
+ * Test Suite: Orchestrator
+ */
+test('Orchestrator - Wake order respects dependencies', async (t) => {
+  const registry = new ServiceRegistry();
+
+  const yaml = `
+services:
+  dev:
+    auth:
+      url: https://auth.test
+      health: /health
+      wake: /wake
+      dependsOn: []
+    payment:
+      url: https://payment.test
+      health: /health
+      wake: /wake
+      dependsOn: [auth]
+`;
+
+  await registry.loadFromString(yaml, 'yaml');
+  const orchestrator = new Orchestrator(registry);
+
+  const order = registry.resolveWakeOrder('payment', 'dev');
+
+  assert.equal(order[0].name, 'auth', 'Auth should wake first');
+  assert.equal(order[1].name, 'payment', 'Payment should wake second');
+});
+
+test('Orchestrator - Set and get service state', async (t) => {
+  const registry = new ServiceRegistry();
+
+  const yaml = `
+services:
+  dev:
+    auth:
+      url: https://auth.test
+      health: /health
+      wake: /wake
+      dependsOn: []
+`;
+
+  await registry.loadFromString(yaml, 'yaml');
+  const orchestrator = new Orchestrator(registry);
+
+  orchestrator._setServiceState('auth', ServiceState.LIVE);
+
+  // Note: In real implementation, would have a getter method
+  assert.ok(orchestrator.serviceStates.has('auth'), 'Should store service state');
+});
+
+/**
+ * Test Suite: Error Handling
+ */
+test('ServiceRegistry - Validate missing required fields', async (t) => {
+  const registry = new ServiceRegistry();
+
+  const invalidYaml = `
+services:
+  dev:
+    auth:
+      url: https://auth.test
+`;
+
+  try {
+    await registry.loadFromString(invalidYaml, 'yaml');
+    assert.fail('Should have thrown validation error');
+  } catch (error) {
+    assert.ok(error.message.includes('health'), 'Should error on missing health endpoint');
+  }
+});
+
+test('ServiceRegistry - Handle invalid YAML', async (t) => {
+  const registry = new ServiceRegistry();
+
+  const invalidYaml = `
+services:
+  dev: [invalid]
+`;
+
+  try {
+    await registry.loadFromString(invalidYaml, 'yaml');
+    assert.fail('Should have thrown error');
+  } catch (error) {
+    assert.ok(error.message.includes('must be an object'), 'Should error on invalid structure');
+  }
+});
+
+/**
+ * Test Suite: Configuration
+ */
+test('Config - Validate URL format', async (t) => {
+  const { utils } = await import('../src/shared/logger.js');
+
+  assert.ok(utils.isValidUrl('http://localhost:3000'), 'Valid URL');
+  assert.ok(utils.isValidUrl('https://example.com'), 'Valid HTTPS URL');
+  assert.ok(!utils.isValidUrl('not-a-url'), 'Invalid URL');
+});
+
+test('Config - Parse duration strings', async (t) => {
+  const { utils } = await import('../src/shared/logger.js');
+
+  assert.equal(utils.parseDuration('5s'), 5000, 'Parse seconds');
+  assert.equal(utils.parseDuration('2m'), 120000, 'Parse minutes');
+  assert.equal(utils.parseDuration('1h'), 3600000, 'Parse hours');
+});
+
+test('Config - Format duration to readable string', async (t) => {
+  const { utils } = await import('../src/shared/logger.js');
+
+  assert.equal(utils.formatDuration(500), '500ms', 'Format milliseconds');
+  assert.equal(utils.formatDuration(5000), '5.0s', 'Format seconds');
+  assert.equal(utils.formatDuration(65000), '1m 5s', 'Format minutes');
+});
+
+/**
+ * Test Suite: Deep Merge
+ */
+test('Utils - Deep merge objects', async (t) => {
+  const { utils } = await import('../src/shared/logger.js');
+
+  const target = { a: 1, b: { c: 2 } };
+  const source = { b: { d: 3 }, e: 4 };
+  const result = utils.deepMerge(target, source);
+
+  assert.equal(result.a, 1, 'Should preserve target properties');
+  assert.equal(result.b.c, 2, 'Should preserve nested target');
+  assert.equal(result.b.d, 3, 'Should add new nested properties');
+  assert.equal(result.e, 4, 'Should add new properties');
+});
+
+/**
+ * Test Suite: Retry Logic
+ */
+test('Utils - Retry with exponential backoff', async (t) => {
+  const { utils } = await import('../src/shared/logger.js');
+
+  let attempts = 0;
+
+  const result = await utils.retry(
+    async () => {
+      attempts++;
+      if (attempts < 3) {
+        throw new Error('Fail');
+      }
+      return 'success';
+    },
+    5,
+    100
+  );
+
+  assert.equal(result, 'success', 'Should succeed on retry');
+  assert.equal(attempts, 3, 'Should make 3 attempts');
+});
+
+test('Utils - Retry timeout after max attempts', async (t) => {
+  const { utils } = await import('../src/shared/logger.js');
+
+  try {
+    await utils.retry(
+      async () => {
+        throw new Error('Always fails');
+      },
+      3,
+      10
+    );
+    assert.fail('Should have thrown error');
+  } catch (error) {
+    assert.ok(error.message.includes('Always fails'), 'Should throw last error');
+  }
+});
+
+console.log('\n✓ All tests completed');