node-server-orchestrator/README.md

CLI tool for orchestrating Node.js development servers (backend, frontend, databases, etc.)

# Node Server Orchestrator

A CLI tool for orchestrating Node.js development servers across multiple projects. Start, stop, and monitor backend, frontend, database, and other Node.js-based development servers with a unified interface.

## 🚀 Features

- **Multi-Project Support** - Manage servers across different projects
- **Health Monitoring** - Real-time status checks with uptime tracking
- **Error Handling** - Startup failure detection and clear error messages

- **Extensible** - Easy to configure new projects and server types
- **Cross-Platform** - Works on Windows, macOS, and Linux

## 📋 Available Commands

- `start <server-id>` - Start a specific project server
- `stop <server-id>` - Stop a running server
- `status <server-id>` - Get detailed server status with uptime
- `list` - List all configured servers
- `start-all` - Start all servers simultaneously
- `stop-all` - Stop all running servers

## 🛠️ Installation

```bash
npm install -g node-server-orchestrator
```

Or use directly:
```bash
npx node-server-orchestrator
```

## ⚙️ Configuration

Create a configuration file at `~/.config/node-server-orchestrator/config.json`:

```json
{
  "projects": {
    "my-backend": {
      "name": "My Backend API",
      "type": "backend",
      "command": ["npm", "run", "dev"],
      "cwd": "/path/to/my-project",
      "port": 3000,
      "healthPath": "/health",
      "startupTimeout": 10000,
      "description": "My project backend server"
    },
    "my-frontend": {
      "name": "My Frontend App",
      "type": "frontend", 
      "command": ["npm", "start"],
      "cwd": "/path/to/my-project/frontend",
      "port": 3001,
      "healthPath": "/",
      "startupTimeout": 15000,
      "description": "My project frontend development server"
    }
  }
}
```

## 🔧 Usage

### CLI Usage

```bash
# List all available servers
node-server-orchestrator list

# Start a specific server
node-server-orchestrator start example-backend

# Stop a specific server  
node-server-orchestrator stop example-backend

# Check server status
node-server-orchestrator status example-backend

# Start all servers
node-server-orchestrator start-all

# Stop all servers
node-server-orchestrator stop-all

# Show help
node-server-orchestrator --help
```

### Example Workflow

1. **List available servers**:
   ```
   📋 Available Servers:
   My Backend API (my-backend) - My project backend server
   My Frontend App (my-frontend) - My project frontend development server
   ```

2. **Start a server**:
   ```
   ✅ My Backend API started successfully
   📊 PID: 12345
   🌐 Port: 3000
   ⏰ Started: 2:30:45 PM
   ```

3. **Check status**:
   ```
   🟢 My Backend API is running
   📊 PID: 12345
   🌐 Port: 3000
   ⏰ Started: 2:30:45 PM
   ⏱️  Uptime: 5m 23s
   ```

## 🎯 Use Cases

### Development Workflows
- Start all project servers with one command
- Monitor server health during development
- Automatically restart servers on changes

### CI/CD Integration
- Start test environments programmatically
- Verify server health before deployments
- Manage multiple microservices



## 🔌 API Reference

### Server Configuration

Each server configuration supports:
- `name`: Human-readable server name
- `type`: Server type (backend, frontend, database, etc.)
- `command`: Command array to start the server
- `cwd`: Working directory for the server
- `port`: Port number for health checks
- `healthPath`: HTTP path for health checks
- `startupTimeout`: Maximum startup wait time in milliseconds
- `description`: Server description

### Health Check Protocol

Servers are considered healthy when they respond with HTTP 200/304 on the specified port and health path.

## 🔒 Security Features

The CLI tool includes comprehensive security measures:

### Input Validation
- **Server ID Validation**: Only alphanumeric characters, hyphens, and underscores allowed
- **Command Whitelist**: Only pre-approved commands (`npm`, `node`, `yarn`, `pnpm`, `bun`) can be executed
- **Port Validation**: Port numbers must be between 1-65535
- **Path Validation**: Working directories must be absolute paths
- **Timeout Limits**: Startup timeouts capped at 60 seconds maximum

### Command Injection Protection
- **Shell Execution**: All commands run with `shell: false` to prevent command injection
- **Command Array**: Commands must be provided as arrays, not strings

### Path Traversal Prevention
- **Config Path Sanitization**: Prevents `../` directory traversal in configuration files
- **Absolute Paths**: All working directories must be absolute paths

### Error Information Protection
- **Error Sanitization**: Sensitive paths and IP addresses are redacted from error messages
- **Limited Information**: Error messages provide only necessary information

## 🚨 Error Handling

The MCP server provides clear error messages for:
- **Port conflicts** - When a server is already running
- **Startup failures** - When servers fail to start within timeout
- **Process crashes** - When managed processes terminate unexpectedly
- **Configuration errors** - Invalid server configurations

## 🤝 Contributing

Contributions are welcome! Please feel free to submit pull requests or open issues for bugs and feature requests.

### Development Setup

```bash
git clone https://github.com/swong-fcsllc/node-server-orchestrator.git
cd node-server-orchestrator
npm install
npm run build
npm test
```

## 📄 License

MIT License - see LICENSE file for details.