wilfredwake 1.0.9 → 1.1.0

package/.dockerignore

@@ -0,0 +1,43 @@
+# Git
+.git
+.gitignore
+.github
+
+# Dependencies
+node_modules
+npm-debug.log
+yarn-error.log
+package-lock.json
+
+# Environment
+.env
+.env.local
+.env.*.local
+
+# IDE & Editor
+.vscode
+.idea
+*.swp
+*.swo
+*~
+.DS_Store
+
+# Testing
+tests
+.test.js
+
+# Documentation
+README.md
+QUICKSTART.md
+SERVICE_STATUS_LOGIC.md
+LICENSE
+
+# Build artifacts
+dist
+build
+out
+
+# CI/CD
+.gitlab-ci.yml
+.circleci
+.github/workflows

package/DOCKER.md

@@ -0,0 +1,361 @@
+# Docker Guide for wilfredwake
+
+## Overview
+
+This guide explains how to use Docker with wilfredwake. Three Docker configurations are provided:
+
+- **Dockerfile** - Multi-stage build supporting production and development images
+- **Dockerfile.orchestrator** - Lightweight orchestrator-only image
+- **docker-compose.yml** - Orchestration for all services
+
+---
+
+## Quick Start
+
+### Build the Production Image
+
+```bash
+docker build -t wilfredwake:latest .
+```
+
+### Build the Orchestrator Image
+
+```bash
+docker build -f Dockerfile.orchestrator -t wilfredwake-orchestrator:latest .
+```
+
+### Run with Docker Compose
+
+```bash
+# Start the orchestrator server
+docker-compose up orchestrator
+
+# Run CLI commands
+docker-compose run --rm cli node bin/cli.js status
+
+# Start development environment
+docker-compose up dev
+```
+
+---
+
+## Docker Images
+
+### Main Dockerfile
+
+Multi-stage Dockerfile with 3 targets:
+
+#### **production** (default)
+- Alpine-based Node.js 18
+- Production dependencies only
+- Optimized for size (~200MB)
+- Includes health checks for orchestrator mode
+
+**Build:**
+```bash
+docker build -t wilfredwake:latest .
+```
+
+**Run:**
+```bash
+# Show help
+docker run --rm wilfredwake:latest bin/cli.js --help
+
+# Check status
+docker run --rm -v $(pwd)/src/config/services.yaml:/app/src/config/services.yaml wilfredwake:latest bin/cli.js status
+
+# Wake a service
+docker run --rm -v $(pwd)/src/config/services.yaml:/app/src/config/services.yaml wilfredwake:latest bin/cli.js wake [service-name]
+
+# Run orchestrator
+docker run -p 3000:3000 -v $(pwd)/src/config/services.yaml:/app/src/config/services.yaml wilfredwake:latest src/orchestrator/server.js
+```
+
+#### **development**
+- Alpine-based Node.js 18
+- All dependencies (including devDependencies)
+- Watch mode enabled (`--experimental-watch`)
+- Full source code mounted via volumes
+
+**Build:**
+```bash
+docker build --target development -t wilfredwake:dev .
+```
+
+**Run:**
+```bash
+docker run -v $(pwd):/app wilfredwake:dev --experimental-watch bin/cli.js --help
+```
+
+### Orchestrator Dockerfile
+
+Lightweight image for just the orchestrator server:
+
+**Build:**
+```bash
+docker build -f Dockerfile.orchestrator -t wilfredwake-orchestrator:latest .
+```
+
+**Run:**
+```bash
+docker run -p 3000:3000 \
+  -v $(pwd)/src/config/services.yaml:/app/src/config/services.yaml \
+  -e ORCHESTRATOR_PORT=3000 \
+  wilfredwake-orchestrator:latest
+```
+
+---
+
+## Docker Compose
+
+### Services
+
+#### **orchestrator** (default)
+REST API server running on port 3000
+```bash
+docker-compose up orchestrator
+```
+
+#### **cli**
+Run CLI commands
+```bash
+docker-compose run --rm cli node bin/cli.js status
+```
+
+#### **dev**
+Development environment with watch mode
+```bash
+docker-compose up dev
+```
+
+### Common Commands
+
+```bash
+# Start orchestrator
+docker-compose up orchestrator
+
+# Run a CLI command
+docker-compose run --rm cli node bin/cli.js wake my-service
+
+# View logs
+docker-compose logs -f orchestrator
+
+# Stop all services
+docker-compose down
+
+# Clean up volumes
+docker-compose down -v
+
+# Rebuild images
+docker-compose up --build orchestrator
+```
+
+### Configuration
+
+Edit `docker-compose.yml` to:
+- Change ports
+- Add environment variables
+- Mount additional volumes
+- Configure networking
+
+Example - run orchestrator on port 5000:
+```yaml
+orchestrator:
+  ...
+  ports:
+    - "5000:3000"
+  environment:
+    - ORCHESTRATOR_PORT=5000
+```
+
+---
+
+## Environment Variables
+
+### In Docker
+
+Set via `docker run -e`:
+```bash
+docker run -e NODE_ENV=production -e ORCHESTRATOR_PORT=3000 wilfredwake:latest
+```
+
+Or in `docker-compose.yml`:
+```yaml
+environment:
+  - NODE_ENV=production
+  - ORCHESTRATOR_PORT=3000
+```
+
+### Configuration Files
+
+Mount your `services.yaml` and `.env`:
+```bash
+docker run -v /path/to/services.yaml:/app/src/config/services.yaml \
+           -v /path/to/.env:/app/.env \
+           wilfredwake:latest
+```
+
+---
+
+## Health Checks
+
+Both images include health checks for orchestrator mode:
+
+```bash
+# Check if orchestrator is healthy
+docker-compose ps orchestrator
+
+# View health status
+docker inspect wilfredwake-orchestrator | grep -A 10 '"Health"'
+```
+
+---
+
+## Networking
+
+### Within Docker Compose
+Services communicate via `wilfredwake-network`:
+```yaml
+networks:
+  - wilfredwake-network
+```
+
+Access orchestrator from CLI container:
+```bash
+http://orchestrator:3000
+```
+
+### External Access
+- Orchestrator exposed on `localhost:3000`
+- CLI container doesn't expose ports (runs commands)
+
+---
+
+## Troubleshooting
+
+### Build Issues
+
+**Missing dependencies:**
+```bash
+docker build --no-cache -t wilfredwake:latest .
+```
+
+**Verify image contents:**
+```bash
+docker run -it --rm wilfredwake:latest sh
+# Inside container:
+# ls -la /app
+# npm ls
+```
+
+### Runtime Issues
+
+**Check logs:**
+```bash
+docker logs wilfredwake-orchestrator
+docker-compose logs -f orchestrator
+```
+
+**Verify volume mounts:**
+```bash
+docker run -it --rm -v $(pwd)/src/config/services.yaml:/app/src/config/services.yaml wilfredwake:latest ls -la src/config/
+```
+
+**Debug networking:**
+```bash
+docker network inspect wilfredwake_wilfredwake-network
+```
+
+---
+
+## Production Considerations
+
+1. **Image Size**: Production image uses Alpine (~200MB)
+2. **Security**: Uses non-root Node process
+3. **Health Checks**: Built-in for orchestrator mode
+4. **Logging**: Configure via environment variables
+5. **Volumes**: Mount config files as read-only when possible
+
+Example production deployment:
+```bash
+docker run -d \
+  --name wilfredwake-orchestrator \
+  --restart=unless-stopped \
+  -p 3000:3000 \
+  -v /etc/wilfredwake/services.yaml:/app/src/config/services.yaml:ro \
+  -v /etc/wilfredwake/.env:/app/.env:ro \
+  -e NODE_ENV=production \
+  wilfredwake:latest \
+  src/orchestrator/server.js
+```
+
+---
+
+## CI/CD Integration
+
+### GitHub Actions Example
+
+```yaml
+- name: Build Docker image
+  run: docker build -t wilfredwake:${{ github.sha }} .
+
+- name: Run tests in container
+  run: docker run --rm wilfredwake:latest npm test
+
+- name: Push to registry
+  run: docker push registry.example.com/wilfredwake:${{ github.sha }}
+```
+
+---
+
+## Advanced Usage
+
+### Custom Entrypoint
+
+```bash
+docker run --entrypoint /bin/sh -it wilfredwake:latest
+```
+
+### Multi-Container Setup
+
+```bash
+# Terminal 1: Start orchestrator
+docker-compose up orchestrator
+
+# Terminal 2: Run CLI in same network
+docker-compose run --rm cli node bin/cli.js health
+```
+
+### Using with Kubernetes
+
+Create Kubernetes manifests based on these Docker images. Example deployment:
+
+```yaml
+apiVersion: v1
+kind: Pod
+metadata:
+  name: wilfredwake-orchestrator
+spec:
+  containers:
+  - name: orchestrator
+    image: wilfredwake:latest
+    command: ["node", "src/orchestrator/server.js"]
+    ports:
+    - containerPort: 3000
+    volumeMounts:
+    - name: config
+      mountPath: /app/src/config
+  volumes:
+  - name: config
+    configMap:
+      name: wilfredwake-config
+```
+
+---
+
+## Questions?
+
+For more information, see:
+- [README.md](README.md)
+- [QUICKSTART.md](QUICKSTART.md)
+- [SERVICE_STATUS_LOGIC.md](SERVICE_STATUS_LOGIC.md)

package/Dockerfile

@@ -0,0 +1,59 @@
+# Multi-stage build for wilfredwake
+FROM node:18-alpine AS base
+
+WORKDIR /app
+
+# Install dependencies stage
+FROM base AS dependencies
+COPY package*.json ./
+RUN npm ci --only=production
+
+# Development dependencies stage
+FROM base AS dev-dependencies
+COPY package*.json ./
+RUN npm ci
+
+# Production image
+FROM base AS production
+
+LABEL maintainer="Wilfred Wake"
+LABEL description="CLI Tool for Multi-Developer Development Environment Wake & Status Management"
+
+# Set environment to production
+ENV NODE_ENV=production
+ENV PATH="/app/node_modules/.bin:$PATH"
+
+# Copy production dependencies
+COPY --from=dependencies /app/node_modules ./node_modules
+
+# Copy application code
+COPY . .
+
+# Make CLI executable
+RUN chmod +x bin/cli.js
+
+# Health check for orchestrator mode
+HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
+    CMD node -e "require('http').get('http://localhost:3000/health', (r) => {if (r.statusCode !== 200) throw new Error(r.statusCode)})" || exit 1
+
+# Default to CLI - can be overridden to run orchestrator server
+ENTRYPOINT ["node"]
+CMD ["bin/cli.js", "--help"]
+
+# Development image
+FROM base AS development
+
+ENV NODE_ENV=development
+ENV PATH="/app/node_modules/.bin:$PATH"
+
+# Copy all dependencies (including devDependencies)
+COPY --from=dev-dependencies /app/node_modules ./node_modules
+
+# Copy application code
+COPY . .
+
+# Make CLI executable
+RUN chmod +x bin/cli.js
+
+ENTRYPOINT ["node"]
+CMD ["--experimental-watch", "bin/cli.js", "--help"]

package/Dockerfile.orchestrator

@@ -0,0 +1,29 @@
+# Lightweight orchestrator-only image
+FROM node:18-alpine
+
+WORKDIR /app
+
+LABEL maintainer="Wilfred Wake"
+LABEL description="Orchestrator API Server for wilfredwake"
+
+ENV NODE_ENV=production
+ENV ORCHESTRATOR_PORT=3000
+ENV ORCHESTRATOR_HOST=0.0.0.0
+ENV PATH="/app/node_modules/.bin:$PATH"
+
+# Install dependencies
+COPY package*.json ./
+RUN npm ci --only=production && npm cache clean --force
+
+# Copy application code
+COPY src/ ./src/
+COPY .env* ./
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
+    CMD node -e "require('http').get('http://localhost:3000/health', (r) => {if (r.statusCode !== 200) throw new Error(r.statusCode)})" || exit 1
+
+EXPOSE 3000
+
+ENTRYPOINT ["node"]
+CMD ["src/orchestrator/server.js"]

package/docker-compose.yml

@@ -0,0 +1,74 @@
+version: '3.9'
+
+services:
+  # CLI container - for running wilfredwake commands
+  cli:
+    build:
+      context: .
+      dockerfile: Dockerfile
+      target: production
+    container_name: wilfredwake-cli
+    image: wilfredwake:latest
+    environment:
+      - NODE_ENV=production
+    volumes:
+      - ./src/config/services.yaml:/app/src/config/services.yaml
+      - ./.env:/app/.env
+    # Override to run specific commands
+    # command: node bin/cli.js status
+    # or: node bin/cli.js wake [service-name]
+    # or: node bin/cli.js health [service-name]
+    # or: node bin/cli.js init
+    profiles:
+      - cli
+
+  # Orchestrator server - for running the REST API
+  orchestrator:
+    build:
+      context: .
+      dockerfile: Dockerfile
+      target: production
+    container_name: wilfredwake-orchestrator
+    image: wilfredwake:latest
+    environment:
+      - NODE_ENV=production
+      - ORCHESTRATOR_PORT=3000
+      - ORCHESTRATOR_HOST=0.0.0.0
+    ports:
+      - "3000:3000"
+    volumes:
+      - ./src/config/services.yaml:/app/src/config/services.yaml
+      - ./.env:/app/.env
+    command: node src/orchestrator/server.js
+    healthcheck:
+      test: ["CMD", "node", "-e", "require('http').get('http://localhost:3000/health', (r) => {if (r.statusCode !== 200) throw new Error(r.statusCode)})"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 5s
+    profiles:
+      - orchestrator
+      - default
+    networks:
+      - wilfredwake-network
+
+  # Development container with watch mode
+  dev:
+    build:
+      context: .
+      dockerfile: Dockerfile
+      target: development
+    container_name: wilfredwake-dev
+    image: wilfredwake:dev
+    environment:
+      - NODE_ENV=development
+    volumes:
+      - .:/app
+      - /app/node_modules
+    command: node --experimental-watch bin/cli.js --help
+    profiles:
+      - dev
+
+networks:
+  wilfredwake-network:
+    driver: bridge

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wilfredwake",
-  "version": "1.0.9",
+  "version": "1.1.0",
   "description": "CLI Tool for Multi-Developer Development Environment Wake & Status Management",
   "type": "module",
   "main": "index.js",

package/src/config/services.yaml

@@ -25,7 +25,11 @@ services:
     # Frontend service
     frontend:
       url: https://transactions-k6gk.onrender.com
-      health: /health
+      # Root page (/) — this is a browser page URL. Orchestrator will
+      # treat a failed HTTP request as LIVE if a TCP connection to the
+      # host:port succeeds (covers cases where the page doesn't return
+      # a standard HTTP status but the site is up).
+      health: /
       dependsOn: []
       description: "frontend Service"
 
@@ -43,13 +47,6 @@ services:
       dependsOn: []
       description: "Notification Event Consumer"
 
-    # Notification producer
-    notification-producer:
-      url: https://notification-service-producer.onrender.com
-      health: /health
-      dependsOn: []
-      description: "Notification Producer Service"
-
   # Staging environment (same services as dev)
   staging: *dev_services
 

package/src/orchestrator/orchestrator.js

@@ -7,6 +7,7 @@
  */
 
 import axios from 'axios';
+import net from 'net';
 
 /**
  * Service state enumeration
@@ -74,29 +75,22 @@ export class Orchestrator {
     // ASSUME ALL SERVICES ARE DEAD INITIALLY
     // NEW: Instead of /wake endpoint, just check /health repeatedly
     // ═══════════════════════════════════════════════════════════════
-    const results = [];
+    const results = new Map();
+    const serviceStartTimes = new Map();
     const startTime = Date.now();
 
+    // Initialize state for each service and do an initial check
     for (const service of services) {
-      const serviceStartTime = Date.now();
+      this._logTimestamp(service.name, 'Wake initiated');
+      this._setServiceState(service.name, ServiceState.DEAD);
+      this._recordLastWakeTime(service.name);
+      serviceStartTimes.set(service.name, Date.now());
 
       try {
-        // NEW: Mark service as being woken and initiate health check sequence
-        this._logTimestamp(service.name, 'Wake initiated');
+        const status = await this._checkHealthWithTimeout(service, Math.min(timeout, 10));
+        const duration = Date.now() - serviceStartTimes.get(service.name);
 
-        // NEW: Set state to DEAD initially (always assume dead)
-        this._setServiceState(service.name, ServiceState.DEAD);
-        this._recordLastWakeTime(service.name);
-
-        // Check health status (handles timeout internally)
-        const status = await this._checkHealthWithTimeout(
-          service,
-          timeout
-        );
-
-        const duration = Date.now() - serviceStartTime;
-
-        results.push({
+        results.set(service.name, {
           name: service.name,
           status,
           url: service.url,
@@ -107,9 +101,8 @@ export class Orchestrator {
 
         this._setServiceState(service.name, status);
       } catch (error) {
-        const duration = Date.now() - serviceStartTime;
-
-        results.push({
+        const duration = Date.now() - serviceStartTimes.get(service.name);
+        results.set(service.name, {
           name: service.name,
           status: ServiceState.FAILED,
           url: service.url,
@@ -117,18 +110,92 @@ export class Orchestrator {
           error: error.message,
           lastWakeTime: this.lastWakeTime.get(service.name),
         });
-
         this._setServiceState(service.name, ServiceState.FAILED);
       }
     }
 
+    // If caller doesn't want to wait, return early with current statuses
+    const toArray = () => Array.from(results.values());
+    let allLive = toArray().every(r => r.status === ServiceState.LIVE);
+    if (!wait || allLive) {
+      const totalDuration = Date.now() - startTime;
+      return {
+        success: allLive,
+        error: null,
+        services: toArray(),
+        totalDuration,
+      };
+    }
+
+    // Otherwise, poll remaining services until all are LIVE or timeout
+    const deadline = Date.now() + timeout * 1000;
+
+    while (Date.now() < deadline) {
+      // Check remaining services concurrently
+      const checks = [];
+      for (const service of services) {
+        const current = results.get(service.name);
+        if (current.status === ServiceState.LIVE) continue;
+
+        checks.push((async () => {
+          const health = await this._performHealthCheck(service);
+          if (health && health.state === ServiceState.LIVE) {
+            const duration = Date.now() - serviceStartTimes.get(service.name);
+            results.set(service.name, {
+              name: service.name,
+              status: ServiceState.LIVE,
+              url: service.url,
+              duration,
+              error: null,
+              lastWakeTime: this.lastWakeTime.get(service.name),
+            });
+            this._setServiceState(service.name, ServiceState.LIVE);
+            this._logTimestamp(service.name, `Became LIVE after ${duration}ms`);
+          } else if (health && health.state === ServiceState.DEAD) {
+            // still dead, update responseTime as duration
+            results.set(service.name, Object.assign({}, results.get(service.name), {
+              status: ServiceState.DEAD,
+              duration: Date.now() - serviceStartTimes.get(service.name),
+              error: health.error || results.get(service.name).error,
+            }));
+          } else if (health && health.state) {
+            // other intermediate state (waking/failed)
+            results.set(service.name, Object.assign({}, results.get(service.name), {
+              status: health.state,
+              duration: Date.now() - serviceStartTimes.get(service.name),
+              error: health.error || null,
+            }));
+          }
+        })());
+      }
+
+      // Wait for this round
+      await Promise.all(checks);
+
+      // Display progress summary
+      const summary = {
+        total: services.length,
+        live: toArray().filter(s => s.status === ServiceState.LIVE).length,
+        waking: toArray().filter(s => s.status === ServiceState.WAKING).length,
+        dead: toArray().filter(s => s.status === ServiceState.DEAD).length,
+        failed: toArray().filter(s => s.status === ServiceState.FAILED).length,
+      };
+
+      this._logTimestamp('orchestrator', `Progress: ${summary.live}/${summary.total} live, ${summary.waking} waking, ${summary.dead} dead, ${summary.failed} failed`);
+
+      allLive = toArray().every(r => r.status === ServiceState.LIVE);
+      if (allLive) break;
+
+      // small delay before next round
+      await this._wait(1000);
+    }
+
     const totalDuration = Date.now() - startTime;
-    const allLive = results.every(r => r.status === ServiceState.LIVE);
 
     return {
-      success: allLive,
+      success: toArray().every(r => r.status === ServiceState.LIVE),
       error: null,
-      services: results,
+      services: toArray(),
       totalDuration,
     };
   }
@@ -163,6 +230,20 @@ export class Orchestrator {
         status = health.state;
       }
 
+      // Special rule: frontend may return an empty body or non-standard response
+      // that doesn't set a numeric statusCode in some environments. Per user
+      // requirement, treat the `frontend` service as LIVE if it returned no
+      // explicit error (i.e. health exists and no DEAD state). This ensures
+      // "nothing returned" from frontend is interpreted as live.
+      if (
+        service.name === 'frontend' &&
+        health &&
+        (health.statusCode == null) &&
+        health.state !== ServiceState.DEAD
+      ) {
+        status = ServiceState.LIVE;
+      }
+
       statusResults.push({
         name: service.name,
         status,
@@ -335,6 +416,55 @@ export class Orchestrator {
         service.name,
         `Health check failed: ${error.message} (DEAD - no response, needs waking)`
       );
+      // If this is a frontend/page-style service (health is '/'), a
+      // failed HTTP request can still mean the site is "live" if the
+      // host accepts TCP connections. Try a TCP connect to the host:port
+      // before marking it DEAD. This covers cases where the page itself
+      // doesn't return a normal HTTP status but the server is responsive
+      // (stops loading in a browser).
+      try {
+        if (service.health === '/' || service.health === '') {
+          const parsed = new URL(service.url);
+          const port = parsed.port ? parseInt(parsed.port, 10) : (parsed.protocol === 'https:' ? 443 : 80);
+          const host = parsed.hostname;
+
+          this._logTimestamp(service.name, `HTTP failed; attempting TCP connect to ${host}:${port}`);
+
+          const tcpStart = Date.now();
+          const tcpOk = await new Promise((resolve) => {
+            const socket = new net.Socket();
+            let settled = false;
+
+            const onCleanup = (ok) => {
+              if (settled) return;
+              settled = true;
+              try { socket.destroy(); } catch (e) {}
+              resolve(ok);
+            };
+
+            socket.setTimeout(3000);
+            socket.once('connect', () => onCleanup(true));
+            socket.once('timeout', () => onCleanup(false));
+            socket.once('error', () => onCleanup(false));
+            socket.connect(port, host);
+          });
+
+          const tcpResponseTime = Date.now() - tcpStart;
+
+          if (tcpOk) {
+            this._logTimestamp(service.name, `TCP connect succeeded in ${tcpResponseTime}ms - treating as LIVE`);
+            return {
+              state: ServiceState.LIVE,
+              statusCode: null,
+              responseTime: tcpResponseTime,
+              error: null,
+              uptime: null,
+            };
+          }
+        }
+      } catch (tcpErr) {
+        this._logTimestamp(service.name, `TCP fallback failed: ${tcpErr.message}`);
+      }
 
       return {
         state: ServiceState.DEAD,  // No response received = service needs waking