wilfredwake 1.0.0

package/bin/cli.js

@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+
+/**
+ * ╔═══════════════════════════════════════════════════════════════╗
+ * ║                                                               ║
+ * ║   WILFREDWAKE - CLI TOOL FOR SERVICE ORCHESTRATION           ║
+ * ║   Multi-Developer Development Environment Management          ║
+ * ║                                                               ║
+ * ║   Entry Point: Main CLI executable with command routing      ║
+ * ║   Uses Commander.js for robust command-line interface        ║
+ * ║                                                               ║
+ * ╚═══════════════════════════════════════════════════════════════╝
+ */
+
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { initCommand } from '../src/cli/commands/init.js';
+import { statusCommand } from '../src/cli/commands/status.js';
+import { wakeCommand } from '../src/cli/commands/wake.js';
+import { healthCommand } from '../src/cli/commands/health.js';
+
+// ═══════════════════════════════════════════════════════════════
+// MAIN CLI SETUP
+// ═══════════════════════════════════════════════════════════════
+
+const program = new Command();
+
+program
+  .name('wilfredwake')
+  .description(
+    chalk.cyan('🌅 CLI Tool for Multi-Developer Development Environment Wake & Status Management')
+  )
+  .version('1.0.0')
+  .usage(chalk.yellow('[command] [options]'));
+
+// ═══════════════════════════════════════════════════════════════
+// COMMAND REGISTRATION
+// ═══════════════════════════════════════════════════════════════
+
+/**
+ * INIT COMMAND
+ * Initializes wilfredwake configuration on first-time setup
+ * Sets up ~/.wilfredwake directory and config.json
+ */
+program
+  .command('init')
+  .description(
+    chalk.magenta('Initialize wilfredwake configuration (first-time setup)')
+  )
+  .option('-o, --orchestrator <url>', 'Orchestrator URL', 'http://localhost:3000')
+  .option('-t, --token <token>', 'Developer API token')
+  .action(initCommand);
+
+/**
+ * STATUS COMMAND
+ * Displays current status of all services
+ * Connects to orchestrator for real-time state
+ */
+program
+  .command('status [service]')
+  .description(chalk.green('Check status of all services or a specific service'))
+  .option('-e, --env <environment>', 'Environment (dev, staging, prod)', 'dev')
+  .option('-f, --format <format>', 'Output format (table, json)', 'table')
+  .action(statusCommand);
+
+/**
+ * WAKE COMMAND
+ * Wakes services on demand with dependency ordering
+ * Defaults to all services if no target specified
+ * Supports waking individual services, groups, or all services
+ */
+program
+  .command('wake [target]')
+  .description(chalk.blue('Wake services on demand (all, <service>, or <group>)'))
+  .option('-e, --env <environment>', 'Environment (dev, staging, prod)', 'dev')
+  .option('--no-wait', 'Don\'t wait for services to be ready')
+  .option('--timeout <seconds>', 'Timeout for service readiness', '300')
+  .action(wakeCommand);
+
+/**
+ * HEALTH COMMAND
+ * Performs health check on services without waking
+ * Useful for monitoring and diagnostics
+ */
+program
+  .command('health [service]')
+  .description(chalk.cyan('Check health status of services'))
+  .option('-e, --env <environment>', 'Environment (dev, staging, prod)', 'dev')
+  .action(healthCommand);
+
+// ═══════════════════════════════════════════════════════════════
+// HELP & ERROR HANDLING
+// ═══════════════════════════════════════════════════════════════
+
+// Default help message with visual enhancements
+program.on('--help', () => {
+  console.log('');
+  console.log(chalk.dim('Examples:'));
+  console.log(chalk.yellow('  $ wilfredwake init                  # Setup configuration'));
+  console.log(chalk.yellow('  $ wilfredwake status                # Check all services'));
+  console.log(chalk.yellow('  $ wilfredwake wake all              # Wake all services'));
+  console.log(chalk.yellow('  $ wilfredwake wake auth             # Wake single service'));
+  console.log(chalk.yellow('  $ wilfredwake health                # Check health'));
+  console.log('');
+  console.log(
+    chalk.dim(
+      'For more information, visit: https://github.com/wilfred/wilfredwake'
+    )
+  );
+  console.log('');
+});
+
+// Error handling for unknown commands
+program.on('command:*', () => {
+  console.error(
+    chalk.red(
+      '\n❌ Invalid command. Use --help for available commands.\n'
+    )
+  );
+  process.exit(1);
+});
+
+// ═══════════════════════════════════════════════════════════════
+// CLI EXECUTION
+// ═══════════════════════════════════════════════════════════════
+
+// Parse command-line arguments and execute
+program.parse(process.argv);
+
+// Show help if no command provided
+if (process.argv.length < 3) {
+  program.outputHelp();
+}

package/index.js

@@ -0,0 +1,222 @@
+/**
+ * ╔═══════════════════════════════════════════════════════════════╗
+ * ║                                                               ║
+ * ║   WILFREDWAKE - CLI TOOL FOR SERVICE ORCHESTRATION           ║
+ * ║                                                               ║
+ * ║   Multi-Developer Development Environment Management          ║
+ * ║   Wake & Status Management for Distributed Systems            ║
+ * ║                                                               ║
+ * ║   Project: wilfredwake                                       ║
+ * ║   Version: 1.0.0                                             ║
+ * ║   License: MIT                                               ║
+ * ║                                                               ║
+ * ╚═══════════════════════════════════════════════════════════════╝
+ *
+ * PURPOSE
+ * ═══════════════════════════════════════════════════════════════
+ * wilfredwake is a CLI tool to manage sleeping development services
+ * in distributed systems, ensuring developers can wake services on
+ * demand while respecting dependency order and checking readiness.
+ *
+ * CORE FEATURES
+ * ═══════════════════════════════════════════════════════════════
+ * • Service status checking and health monitoring
+ * • On-demand service waking with dependency awareness
+ * • Multi-developer support with centralized orchestrator
+ * • Configuration-driven service registry (YAML/JSON)
+ * • Human-readable colored output
+ * • Timeout and error handling
+ * • Multi-environment support (dev, staging, prod)
+ *
+ * ARCHITECTURE
+ * ═══════════════════════════════════════════════════════════════
+ * Developer CLI → Orchestrator (always-on) → Services
+ *
+ * CLI: Local interface developers use (this package)
+ * Orchestrator: Backend service managing state and wake operations
+ * Services: Individual microservices with /health and /wake endpoints
+ *
+ * SYSTEM COMPONENTS
+ * ═══════════════════════════════════════════════════════════════
+ * src/
+ *   ├── cli/                    # CLI interface
+ *   │   ├── commands/           # CLI command implementations
+ *   │   │   ├── init.js         # Configuration setup
+ *   │   │   ├── status.js       # Service status checking
+ *   │   │   ├── wake.js         # Service wake operations
+ *   │   │   └── health.js       # Health checks
+ *   │   ├── config.js           # Configuration management
+ *   │   └── utils.js            # CLI utilities
+ *   ├── orchestrator/           # Backend orchestrator
+ *   │   ├── server.js           # Express.js API server
+ *   │   ├── registry.js         # Service registry loader
+ *   │   ├── orchestrator.js     # Wake orchestration logic
+ *   │   └── handlers/           # API request handlers
+ *   ├── shared/                 # Shared modules
+ *   │   ├── colors.js           # Color schemes and formatting
+ *   │   ├── logger.js           # Logging utilities
+ *   │   └── errors.js           # Error definitions
+ *   └── config/                 # Configuration files
+ *       └── services.yaml       # Service registry
+ *   ├── bin/                    # Executable entry point
+ *   │   └── cli.js              # CLI executable
+ *   ├── package.json            # NPM package definition
+ *   └── index.js                # Main entry point
+ *
+ * USAGE EXAMPLES
+ * ═══════════════════════════════════════════════════════════════
+ *
+ * # Initialize configuration (first-time setup)
+ * $ wilfredwake init
+ *
+ * # Check status of all services
+ * $ wilfredwake status
+ *
+ * # Check specific service status
+ * $ wilfredwake status auth
+ *
+ * # Wake all services
+ * $ wilfredwake wake all
+ *
+ * # Wake specific service
+ * $ wilfredwake wake auth
+ *
+ * # Wake service group
+ * $ wilfredwake wake payments
+ *
+ * # Health check (no waking)
+ * $ wilfredwake health
+ *
+ * # Environment-specific operations
+ * $ wilfredwake wake all --env staging
+ *
+ * # JSON output format
+ * $ wilfredwake status --format json
+ *
+ * CONFIGURATION
+ * ═══════════════════════════════════════════════════════════════
+ * Configuration is stored in ~/.wilfredwake/config.json
+ *
+ * Default values:
+ * {
+ *   "orchestratorUrl": "http://localhost:3000",
+ *   "token": null,
+ *   "environment": "dev",
+ *   "preferences": {
+ *     "outputFormat": "table",
+ *     "verbose": false,
+ *     "autoWait": true,
+ *     "timeout": 300
+ *   }
+ * }
+ *
+ * SERVICE REGISTRY
+ * ═══════════════════════════════════════════════════════════════
+ * Service registry (services.yaml) defines:
+ * • Service name, URL, and health/wake endpoints
+ * • Service dependencies (for dependency-aware waking)
+ * • Environment configurations (dev, staging, prod)
+ * • Service grouping for bulk operations
+ *
+ * Example service definition:
+ * services:
+ *   dev:
+ *     auth:
+ *       url: https://auth-dev.onrender.com
+ *       health: /health
+ *       wake: /wake
+ *       dependsOn: []
+ *
+ *     payment-consumer:
+ *       url: https://payment-consumer-dev.onrender.com
+ *       health: /health
+ *       wake: /wake
+ *       dependsOn: [auth]
+ *
+ * ORCHESTRATOR API
+ * ═══════════════════════════════════════════════════════════════
+ * The orchestrator backend provides REST APIs:
+ *
+ * GET  /health                 - Orchestrator health check
+ * GET  /api/status             - Get service status
+ * GET  /api/health             - Perform health checks
+ * POST /api/wake               - Wake services
+ * GET  /api/registry           - View service registry
+ * POST /api/reload             - Reload service registry
+ *
+ * MULTI-DEVELOPER SUPPORT
+ * ═══════════════════════════════════════════════════════════════
+ * • CLI uses per-user token to identify developer
+ * • Orchestrator is shared/always-on (single source of truth)
+ * • Multiple developers can wake services concurrently
+ * • State is centralized in orchestrator
+ *
+ * DEPENDENCY ORDERING
+ * ═══════════════════════════════════════════════════════════════
+ * Services are woken in dependency order using topological sort:
+ *
+ * Example dependency chain:
+ * auth (no deps) → payment-producer (depends on auth)
+ *              → payment-consumer (depends on payment-producer)
+ *
+ * When waking "all":
+ * 1. auth wakes first
+ * 2. Once auth is ready, payment-producer wakes
+ * 3. Once payment-producer is ready, payment-consumer wakes
+ *
+ * HEALTH CHECKS
+ * ═══════════════════════════════════════════════════════════════
+ * • Health endpoint: GET {service-url}/health (configurable)
+ * • Wake endpoint: POST {service-url}/wake (configurable)
+ * • Status codes < 300: Service is ready
+ * • Status code 503: Service is sleeping
+ * • Status codes >= 400: Service has issues
+ * • Timeout: Service not responding
+ *
+ * ERROR HANDLING
+ * ═══════════════════════════════════════════════════════════════
+ * • Timeouts: Services that don't respond within timeout
+ * • Failed health checks: Services that fail health validation
+ * • Circular dependencies: Detected and reported
+ * • Connection errors: Clear error messages with guidance
+ * • Partial success: Some services wake, others fail
+ *
+ * ENVIRONMENT VARIABLES
+ * ═══════════════════════════════════════════════════════════════
+ * PORT                 - Orchestrator port (default: 3000)
+ * REGISTRY_FILE        - Path to service registry (default: src/config/services.yaml)
+ * NODE_ENV             - Environment (development, production)
+ * REQUIRE_AUTH         - Require authentication tokens
+ *
+ * FUTURE ENHANCEMENTS
+ * ═══════════════════════════════════════════════════════════════
+ * • CLI auto-completion support
+ * • Hot reload of service registry
+ * • Web UI for orchestration overview
+ * • Scoped groups and service tagging
+ * • API-based dynamic service registration
+ * • Slack/email notifications for sleeping services
+ * • Service metrics and performance tracking
+ * • Automatic health monitoring and alerting
+ * • Service lifecycle management (pause, stop, restart)
+ * • Multi-user authentication and authorization
+ *
+ * LICENSE
+ * ═══════════════════════════════════════════════════════════════
+ * MIT License - See LICENSE file for details
+ *
+ * REFERENCES
+ * ═══════════════════════════════════════════════════════════════
+ * • Render sleeping service behavior
+ * • Kubernetes orchestration concepts
+ * • Terraform infrastructure as code patterns
+ * • DevOps tooling best practices
+ *
+ */
+
+// Entry point - exports CLI version and utilities for programmatic use
+export { default as ConfigManager } from './src/cli/config.js';
+export { Logger, utils } from './src/shared/logger.js';
+export { colors, format } from './src/shared/colors.js';
+export { ServiceRegistry } from './src/orchestrator/registry.js';
+export { Orchestrator, ServiceState } from './src/orchestrator/orchestrator.js';

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "wilfredwake",
+  "version": "1.0.0",
+  "description": "CLI Tool for Multi-Developer Development Environment Wake & Status Management",
+  "type": "module",
+  "main": "index.js",
+  "bin": {
+    "wilfredwake": "./bin/cli.js"
+  },
+  "scripts": {
+    "start": "node bin/cli.js",
+    "dev": "node --experimental-watch bin/cli.js",
+    "orchestrator": "node src/orchestrator/server.js",
+    "orchestrator:dev": "node --experimental-watch src/orchestrator/server.js",
+    "test": "node --test tests/**/*.test.js"
+  },
+  "keywords": [
+    "cli",
+    "service-management",
+    "orchestration",
+    "development",
+    "wake",
+    "status"
+  ],
+  "author": "Wilfred Wake",
+  "license": "MIT",
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "commander": "^11.1.0",
+    "axios": "^1.6.0",
+    "js-yaml": "^4.1.0",
+    "dotenv": "^16.3.1",
+    "express": "^4.18.2"
+  },
+  "devDependencies": {
+    
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/src/cli/commands/health.js

@@ -0,0 +1,238 @@
+/**
+ * ╔═══════════════════════════════════════════════════════════════╗
+ * ║          HEALTH COMMAND - Check Service Health                ║
+ * ║     Performs health checks without waking services            ║
+ * ║     Useful for monitoring and diagnostics                     ║
+ * ╚═══════════════════════════════════════════════════════════════╝
+ */
+
+import axios from 'axios';
+import ConfigManager from '../config.js';
+import { Logger, utils } from '../../shared/logger.js';
+import { colors, format } from '../../shared/colors.js';
+import chalk from 'chalk';
+
+const logger = new Logger();
+
+/**
+ * Check health status of services
+ * Does NOT wake services, only checks their current health
+ *
+ * @param {string} service - Optional service name to check
+ * @param {Object} options - Command options
+ * @param {string} options.env - Environment (dev, staging, prod)
+ */
+export async function healthCommand(service, options) {
+  try {
+    // ═══════════════════════════════════════════════════════════════
+    // LOAD CONFIGURATION
+    // ═══════════════════════════════════════════════════════════════
+    const configManager = new ConfigManager();
+    const config = await configManager.loadConfig();
+
+    const env = options.env || config.environment;
+
+    logger.section('Service Health Check');
+
+    // ═══════════════════════════════════════════════════════════════
+    // FETCH HEALTH FROM ORCHESTRATOR
+    // ═══════════════════════════════════════════════════════════════
+    let stopSpinner;
+    try {
+      stopSpinner = logger.spinner('Checking service health...');
+
+      const response = await axios.get(
+        `${config.orchestratorUrl}/api/health`,
+        {
+          params: {
+            environment: env,
+            service: service || undefined,
+          },
+          timeout: 15000,
+        }
+      );
+
+      stopSpinner();
+      console.log(''); // New line after spinner
+
+      const services = response.data.services || [];
+      const timestamp = response.data.timestamp || new Date().toISOString();
+
+      // ═══════════════════════════════════════════════════════════════
+      // DISPLAY HEALTH RESULTS
+      // ═══════════════════════════════════════════════════════════════
+      _displayHealthStatus(services, env, timestamp);
+
+      // ═══════════════════════════════════════════════════════════════
+      // HEALTH SUMMARY
+      // ═══════════════════════════════════════════════════════════════
+      _displayHealthSummary(services);
+
+      process.exit(0);
+    } catch (error) {
+      stopSpinner?.();
+      throw error;
+    }
+  } catch (error) {
+    logger.error(`Health check failed: ${error.message}`);
+
+    if (error.code === 'ECONNREFUSED') {
+      console.log(
+        chalk.yellowBright(
+          '\n⚠ Could not connect to orchestrator. Make sure it\'s running.'
+        )
+      );
+      console.log(chalk.dim('Run: wilfredwake init'));
+    }
+
+    process.exit(1);
+  }
+}
+
+/**
+ * Display detailed health status
+ * @private
+ * @param {Array} services - Services health data
+ * @param {string} environment - Environment name
+ * @param {string} timestamp - Check timestamp
+ */
+function _displayHealthStatus(services, environment, timestamp) {
+  if (services.length === 0) {
+    logger.info('No services found in registry.');
+    return;
+  }
+
+  console.log(chalk.cyanBright.bold(`\n💓 Health Status (${environment.toUpperCase()})\n`));
+  console.log(chalk.gray(`Last checked: ${new Date(timestamp).toLocaleString()}\n`));
+
+  // ═══════════════════════════════════════════════════════════════
+  // DISPLAY EACH SERVICE'S HEALTH
+  // ═══════════════════════════════════════════════════════════════
+  services.forEach((service) => {
+    const statusEmoji = _getHealthEmoji(service.status);
+    const statusColor = colors.status[service.status] || colors.status.unknown;
+
+    // Service header
+    console.log(
+      `${statusEmoji} ${statusColor.bold(service.name)} ${chalk.gray(
+        `(${service.status})`
+      )}`
+    );
+
+    // Service details
+    if (service.url) {
+      console.log(
+        chalk.dim(`   URL: ${service.url}`)
+      );
+    }
+
+    if (service.responseTime) {
+      const timeColor =
+        service.responseTime > 1000 ? chalk.yellow : chalk.green;
+      console.log(
+        chalk.dim(`   Response time: ${timeColor(
+          `${service.responseTime}ms`
+        )}`)
+      );
+    }
+
+    if (service.lastWakeTime) {
+      const lastWake = new Date(service.lastWakeTime).toLocaleString();
+      console.log(chalk.dim(`   Last woken: ${lastWake}`));
+    }
+
+    if (service.lastChecked) {
+      const lastCheck = new Date(service.lastChecked).toLocaleTimeString();
+      console.log(chalk.dim(`   Last checked: ${lastCheck}`));
+    }
+
+    if (service.statusCode) {
+      const codeColor =
+        service.statusCode < 300 ? chalk.green :
+        service.statusCode < 400 ? chalk.yellow :
+        chalk.red;
+      console.log(
+        chalk.dim(`   Status code: ${codeColor(service.statusCode)}`)
+      );
+    }
+
+    if (service.error) {
+      console.log(chalk.redBright(`   Error: ${service.error}`));
+    }
+
+    if (service.dependencies && service.dependencies.length > 0) {
+      console.log(
+        chalk.dim(`   Dependencies: ${service.dependencies.join(', ')}`)
+      );
+    }
+
+    console.log(''); // Spacing
+  });
+}
+
+/**
+ * Display health summary statistics
+ * @private
+ * @param {Array} services - Services health data
+ */
+function _displayHealthSummary(services) {
+  if (services.length === 0) return;
+
+  const stats = {
+    total: services.length,
+    live: services.filter(s => s.status === 'live').length,
+    waking: services.filter(s => s.status === 'waking').length,
+    dead: services.filter(s => s.status === 'dead').length,
+    failed: services.filter(s => s.status === 'failed').length,
+    unknown: services.filter(s => s.status === 'unknown').length,
+  };
+
+  console.log(chalk.magentaBright.bold('Summary'));
+  console.log(`  Total services: ${stats.total}`);
+  console.log(`  ${chalk.greenBright('✓')} Live: ${chalk.greenBright(
+    stats.live
+  )}`);
+  if (stats.waking > 0) {
+    console.log(`  ${chalk.yellowBright('⟳')} Waking: ${chalk.yellowBright(
+      stats.waking
+    )}`);
+  }
+  if (stats.dead > 0) {
+    console.log(`  ${chalk.gray('⚫')} Dead: ${chalk.gray(
+      stats.dead
+    )}`);
+  }
+  if (stats.failed > 0) {
+    console.log(`  ${chalk.redBright('✗')} Failed: ${chalk.redBright(
+      stats.failed
+    )}`);
+  }
+  if (stats.unknown > 0) {
+    console.log(`  ${chalk.magentaBright('?')} Unknown: ${chalk.magentaBright(
+      stats.unknown
+    )}`);
+  }
+  console.log('');
+}
+
+/**
+ * Get emoji for health status
+ * @private
+ * @param {string} status - Service status
+ * @returns {string} Emoji character
+ */
+function _getHealthEmoji(status) {
+  const emojis = {
+    live: '💚',
+    dead: '😴',
+    waking: '🌅',
+    failed: '❌',
+    unknown: '❓',
+    // Backward compatibility
+    ready: '💚',
+    sleeping: '😴',
+    pending: '⏳',
+  };
+
+  return emojis[status] || '❓';
+}