servherd 0.0.1 → 1.0.0

package/examples/ci-github-actions/workflow.yml

@@ -0,0 +1,195 @@
+# THIS FILE IS AUTO GENERATED: DO NOT EDIT THIS FILE
+# Example GitHub Actions workflow using servherd
+# Copy this to .github/workflows/e2e.yml in your project
+
+name: E2E Tests with servherd
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+    branches: [main, master]
+
+env:
+  CI: true
+  SERVHERD_PORT_MIN: 8000
+  SERVHERD_PORT_MAX: 8100
+
+jobs:
+  e2e-tests:
+    name: E2E Tests
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Install servherd
+        run: npm install -g servherd
+
+      - name: Install Playwright
+        run: npx playwright install --with-deps chromium
+
+      - name: Start development server
+        run: |
+          servherd start --name app -- npm run dev --port {{port}}
+
+          # Wait for server to be ready
+          echo "Waiting for server to start..."
+          sleep 10
+
+          # Get the assigned port
+          APP_PORT=$(servherd info app --json | jq -r '.port')
+          echo "Server running on port $APP_PORT"
+          echo "APP_URL=http://localhost:$APP_PORT" >> $GITHUB_ENV
+
+      - name: Run E2E tests
+        run: npx playwright test
+        env:
+          BASE_URL: ${{ env.APP_URL }}
+
+      - name: Upload test results
+        uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: playwright-report
+          path: playwright-report/
+          retention-days: 7
+
+      - name: Show server logs on failure
+        if: failure()
+        run: |
+          echo "=== Server Logs ==="
+          servherd logs app --lines 100
+          echo "=== Error Logs ==="
+          servherd logs app --error --lines 100
+
+      - name: Cleanup
+        if: always()
+        run: servherd stop --all
+
+
+  # Full-stack example with multiple servers
+  fullstack-e2e:
+    name: Full-Stack E2E Tests
+    runs-on: ubuntu-latest
+
+    services:
+      postgres:
+        image: postgres:15
+        env:
+          POSTGRES_USER: test
+          POSTGRES_PASSWORD: test
+          POSTGRES_DB: testdb
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Install servherd
+        run: npm install -g servherd
+
+      - name: Start backend API
+        run: |
+          servherd start --name api --tag e2e \
+            -- npm run api --port {{port}}
+        env:
+          DATABASE_URL: postgres://test:test@localhost:5432/testdb
+
+      - name: Start frontend
+        run: |
+          # Wait for API to be ready
+          sleep 5
+          API_PORT=$(servherd info api --json | jq -r '.port')
+
+          servherd start --name frontend --tag e2e \
+            -- npm run dev --port {{port}}
+        env:
+          VITE_API_URL: http://localhost:${{ env.API_PORT }}
+
+      - name: Wait for servers
+        run: |
+          sleep 10
+          servherd list --tag e2e
+
+          # Health check
+          FRONTEND_PORT=$(servherd info frontend --json | jq -r '.port')
+          curl -f http://localhost:$FRONTEND_PORT || exit 1
+
+      - name: Run E2E tests
+        run: |
+          FRONTEND_PORT=$(servherd info frontend --json | jq -r '.port')
+          BASE_URL=http://localhost:$FRONTEND_PORT npm run test:e2e
+
+      - name: Cleanup
+        if: always()
+        run: servherd stop --tag e2e
+
+
+  # Matrix testing example
+  cross-browser:
+    name: Cross-Browser Tests
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        browser: [chromium, firefox, webkit]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Install servherd
+        run: npm install -g servherd
+
+      - name: Install Playwright
+        run: npx playwright install --with-deps ${{ matrix.browser }}
+
+      - name: Start server
+        run: |
+          servherd start --name app -- npm run dev --port {{port}}
+          sleep 10
+
+      - name: Run tests on ${{ matrix.browser }}
+        run: |
+          APP_PORT=$(servherd info app --json | jq -r '.port')
+          BASE_URL=http://localhost:$APP_PORT \
+            npx playwright test --project=${{ matrix.browser }}
+
+      - name: Cleanup
+        if: always()
+        run: servherd stop app

package/examples/mcp-claude-code/README.md

@@ -0,0 +1,213 @@
+# Claude Code MCP Integration
+
+This guide shows how to use servherd with Claude Code through the Model Context Protocol (MCP).
+
+## Setup
+
+### 1. Install servherd
+
+```bash
+npm install -g servherd
+```
+
+### 2. Configure Claude Code
+
+Add servherd to your Claude Code MCP configuration:
+
+**Location:** `~/.claude/claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "servherd": {
+      "command": "npx",
+      "args": ["servherd", "mcp"]
+    }
+  }
+}
+```
+
+### 3. Restart Claude Code
+
+After updating the configuration, restart Claude Code to load the new MCP server.
+
+## Using with Claude
+
+Once configured, you can ask Claude to manage your development servers naturally:
+
+### Starting Servers
+
+> **You:** Start a Vite dev server for my React project
+
+Claude will use `servherd_start` to start the server and tell you the assigned port:
+
+> **Claude:** I've started your Vite development server. It's running at http://localhost:5173
+
+### Listing Servers
+
+> **You:** What servers are running?
+
+> **Claude:** You have 2 servers running:
+> - `frontend` (online) - http://localhost:5173 - /home/user/my-project
+> - `api` (online) - http://localhost:3000 - /home/user/my-project/api
+
+### Viewing Server Info
+
+> **You:** Tell me about the frontend server
+
+> **Claude:** Here's the status of your frontend server:
+> - **Name:** frontend
+> - **Status:** online
+> - **URL:** http://localhost:5173
+> - **Uptime:** 2 hours 15 minutes
+> - **Memory:** 125 MB
+> - **CPU:** 0.5%
+
+### Checking Logs
+
+> **You:** Show me the last few log lines from the api server
+
+> **Claude:** Here are the recent logs from your api server:
+> ```
+> [12:34:56] Server listening on port 3000
+> [12:35:01] GET /api/users - 200 (15ms)
+> [12:35:03] POST /api/login - 200 (45ms)
+> ```
+
+### Stopping Servers
+
+> **You:** Stop all the development servers
+
+> **Claude:** I've stopped all your development servers:
+> - frontend - stopped
+> - api - stopped
+
+## Practical Examples
+
+### Full-Stack Development
+
+> **You:** I'm working on a full-stack app with a React frontend and Express backend. Start both servers for me.
+
+> **Claude:** I'll start both servers for you.
+>
+> Started:
+> - Frontend (React/Vite): http://localhost:5173
+> - Backend (Express): http://localhost:3001
+>
+> Both servers are now running and ready for development.
+
+### Debugging
+
+> **You:** The API is returning errors. Can you check the logs?
+
+> **Claude:** Let me check the error logs for your API server...
+>
+> I found some errors in the logs:
+> ```
+> [ERROR] TypeError: Cannot read property 'id' of undefined
+>     at /src/routes/users.js:45:23
+> ```
+>
+> It looks like there's an issue in your users route where it's trying to access an undefined object's `id` property.
+
+### Resource Monitoring
+
+> **You:** Is anything using too much memory?
+
+> **Claude:** Let me check your servers' resource usage...
+>
+> | Server | Memory | CPU |
+> |--------|--------|-----|
+> | frontend | 125 MB | 0.5% |
+> | api | 89 MB | 0.2% |
+> | worker | 256 MB | 5.1% |
+>
+> The worker process is using the most memory at 256 MB and has higher CPU usage. This might be worth investigating if performance is a concern.
+
+### Cleanup
+
+> **You:** I'm done for the day. Clean up all my dev servers.
+
+> **Claude:** I've cleaned up your development environment:
+>
+> Stopped and removed:
+> - frontend
+> - api
+> - worker
+>
+> All servers have been stopped and removed from the registry.
+
+## Available MCP Tools
+
+| Tool | Description |
+|------|-------------|
+| `servherd_start` | Start a new development server |
+| `servherd_stop` | Stop running servers |
+| `servherd_restart` | Restart servers |
+| `servherd_list` | List all managed servers |
+| `servherd_info` | Get detailed server information |
+| `servherd_logs` | View server logs |
+| `servherd_remove` | Remove servers from registry |
+| `servherd_config` | View/modify configuration |
+
+## MCP Resources
+
+Claude can also access these resources directly:
+
+- `servherd://servers` - List of all servers
+- `servherd://servers/{name}` - Details for a specific server
+- `servherd://servers/{name}/logs` - Logs for a specific server
+
+## Tips
+
+### Natural Language
+
+You don't need to know the exact commands. Just describe what you want:
+
+- "Start my development server"
+- "What's running right now?"
+- "Stop the frontend but keep the API running"
+- "Is the server healthy?"
+
+### Context Awareness
+
+Claude remembers previous actions in the conversation:
+
+> **You:** Start a Vite server
+> **Claude:** Started at http://localhost:5173
+>
+> **You:** What port is it on?
+> **Claude:** Your Vite server is running on port 5173
+
+### Error Handling
+
+Claude will explain errors clearly:
+
+> **You:** Start another server with the same name
+> **Claude:** There's already a server named "frontend" running. Would you like me to:
+> 1. Restart the existing server
+> 2. Stop it and start a new one
+> 3. Use a different name for the new server
+
+## Troubleshooting
+
+### MCP Server Not Connecting
+
+1. Check configuration file syntax
+2. Ensure servherd is installed: `npx servherd --version`
+3. Try running manually: `npx servherd mcp`
+4. Restart Claude Code
+
+### Commands Not Working
+
+1. Check if PM2 is installed: `pm2 --version`
+2. Verify permissions on ~/.servherd directory
+3. Check servherd logs for errors
+
+### Getting Help
+
+Ask Claude:
+
+> **You:** What servherd commands are available?
+
+Claude will list all available server management capabilities.

package/examples/multi-server/README.md

@@ -0,0 +1,270 @@
+# Managing Multiple Servers
+
+This example shows how to manage multiple development servers across projects using tags and naming conventions.
+
+## Scenario: Full-Stack Application
+
+A typical full-stack setup with frontend, backend, and background workers:
+
+```bash
+# Frontend (React/Vite)
+servherd start --name frontend --tag web --tag dev -- npx vite --port {{port}}
+
+# Backend API (Node/Express)
+servherd start --name api --tag backend --tag dev -- npm run api --port {{port}}
+
+# Background worker
+servherd start --name worker --tag background --tag dev -- npm run worker
+
+# Database admin (pgAdmin, etc.)
+servherd start --name db-admin --tag tools --tag dev -- npm run db-admin --port {{port}}
+```
+
+## Organizing with Tags
+
+### By Layer
+
+```bash
+# Frontend services
+servherd start --name web --tag frontend -- npm run web --port {{port}}
+servherd start --name mobile-api --tag frontend -- npm run mobile --port {{port}}
+
+# Backend services
+servherd start --name api --tag backend -- npm run api --port {{port}}
+servherd start --name auth --tag backend -- npm run auth --port {{port}}
+
+# Infrastructure
+servherd start --name redis-ui --tag infra -- npm run redis-ui --port {{port}}
+```
+
+### By Environment
+
+```bash
+# Development
+servherd start --name api --tag dev -- npm run dev --port {{port}}
+
+# Staging
+servherd start --name api-staging --tag staging -- npm run staging --port {{port}}
+```
+
+### By Project
+
+```bash
+# Project A
+servherd start --name projecta-web --tag projecta -- npm run web --port {{port}}
+servherd start --name projecta-api --tag projecta -- npm run api --port {{port}}
+
+# Project B
+servherd start --name projectb-web --tag projectb -- npm run web --port {{port}}
+servherd start --name projectb-api --tag projectb -- npm run api --port {{port}}
+```
+
+## Bulk Operations
+
+### Stop by Tag
+
+```bash
+# Stop all frontend servers
+servherd stop --tag frontend
+
+# Stop all Project A servers
+servherd stop --tag projecta
+
+# Stop all dev servers
+servherd stop --tag dev
+```
+
+### List by Tag
+
+```bash
+# List all backend servers
+servherd list --tag backend
+
+# List running dev servers only
+servherd list --tag dev --running
+```
+
+### Restart by Tag
+
+```bash
+# Restart all backend servers after config change
+servherd restart --tag backend
+```
+
+### Remove by Tag
+
+```bash
+# Clean up staging servers
+servherd remove --tag staging --force
+```
+
+## Microservices Example
+
+Managing a microservices architecture:
+
+```bash
+# API Gateway
+servherd start --name gateway --tag core --tag api \
+  -- npm run gateway --port {{port}}
+
+# User Service
+servherd start --name users --tag core --tag api \
+  -- npm run users --port {{port}}
+
+# Order Service
+servherd start --name orders --tag core --tag api \
+  -- npm run orders --port {{port}}
+
+# Payment Service
+servherd start --name payments --tag core --tag api \
+  -- npm run payments --port {{port}}
+
+# Notification Service
+servherd start --name notifications --tag async --tag api \
+  -- npm run notifications --port {{port}}
+
+# Email Worker
+servherd start --name email-worker --tag async --tag worker \
+  -- npm run email-worker
+
+# Report Generator
+servherd start --name reports --tag async --tag worker \
+  -- npm run reports
+```
+
+### Managing the Stack
+
+```bash
+# View entire stack
+servherd list
+
+# View core services only
+servherd list --tag core
+
+# View async services
+servherd list --tag async
+
+# Restart all API services
+servherd restart --tag api
+
+# Stop workers only
+servherd stop --tag worker
+```
+
+## Scripts for Common Operations
+
+Create shell scripts for common tasks:
+
+### start-all.sh
+
+```bash
+#!/bin/bash
+set -e
+
+echo "Starting development stack..."
+
+# Core services
+servherd start --name frontend --tag dev -- npm run frontend --port {{port}}
+servherd start --name api --tag dev -- npm run api --port {{port}}
+servherd start --name worker --tag dev -- npm run worker
+
+# Wait for services to be ready
+sleep 5
+
+# Show status
+servherd list --tag dev
+
+echo "Development stack is running!"
+```
+
+### stop-all.sh
+
+```bash
+#!/bin/bash
+
+echo "Stopping development stack..."
+servherd stop --tag dev
+
+echo "Development stack stopped."
+```
+
+### status.sh
+
+```bash
+#!/bin/bash
+
+echo "=== Development Stack Status ==="
+servherd list --tag dev
+
+echo ""
+echo "=== Resource Usage ==="
+for server in $(servherd list --tag dev --json | jq -r '.[].name'); do
+  echo "--- $server ---"
+  servherd info $server | grep -E "(Memory|CPU|Uptime)"
+done
+```
+
+## Monorepo Pattern
+
+For monorepos with multiple packages:
+
+```bash
+# From repo root
+PROJECT_ROOT=$(pwd)
+
+# Start each package's dev server
+cd $PROJECT_ROOT/packages/web
+servherd start --name web --tag monorepo -- npm run dev --port {{port}}
+
+cd $PROJECT_ROOT/packages/admin
+servherd start --name admin --tag monorepo -- npm run dev --port {{port}}
+
+cd $PROJECT_ROOT/packages/api
+servherd start --name api --tag monorepo -- npm run dev --port {{port}}
+
+cd $PROJECT_ROOT
+servherd list --tag monorepo
+```
+
+## Tips
+
+### Consistent Naming
+
+Use consistent naming conventions:
+
+```
+{project}-{service}  e.g., myapp-frontend, myapp-api
+{service}-{env}      e.g., api-dev, api-staging
+```
+
+### Tag Hierarchy
+
+Use multiple tags for flexible filtering:
+
+```bash
+# Tag by layer, project, and environment
+--tag frontend --tag projecta --tag dev
+```
+
+### Quick Status Check
+
+```bash
+# See what's running
+servherd list --running
+
+# Count servers by tag
+servherd list --tag dev | wc -l
+```
+
+### Resource Monitoring
+
+```bash
+# Check a specific server
+servherd info api
+
+# Quick memory check across all servers
+for s in $(servherd list --json | jq -r '.[].name'); do
+  echo -n "$s: "
+  servherd info $s --json | jq -r '.memory // "not running"'
+done
+```