claude-flow-novice 2.14.37 → 2.15.1

package/claude-assets/cfn-extras/skills/ui-portal/cfn-web-portal/invoke-portal-agents.sh

@@ -0,0 +1,129 @@
+#!/usr/bin/env bash
+# Web Portal Skill - Query Agent Information
+# Usage: ./invoke-portal-agents.sh [--status STATUS] [--type TYPE] [--swarm SWARM_ID] [--agent-id AGENT_ID] [--format json|table]
+#
+# Queries /api/agents with filters for agent hierarchy and status
+
+set -euo pipefail
+
+# Configuration
+DEFAULT_PORT=3000
+DEFAULT_FORMAT="json"
+
+# Parse arguments
+PORT="$DEFAULT_PORT"
+FORMAT="$DEFAULT_FORMAT"
+STATUS_FILTER=""
+TYPE_FILTER=""
+SWARM_FILTER=""
+AGENT_ID=""
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --port)
+      PORT="$2"
+      shift 2
+      ;;
+    --format)
+      FORMAT="$2"
+      shift 2
+      ;;
+    --status)
+      STATUS_FILTER="$2"
+      shift 2
+      ;;
+    --type)
+      TYPE_FILTER="$2"
+      shift 2
+      ;;
+    --swarm)
+      SWARM_FILTER="$2"
+      shift 2
+      ;;
+    --agent-id)
+      AGENT_ID="$2"
+      shift 2
+      ;;
+    *)
+      echo "Unknown argument: $1" >&2
+      exit 1
+      ;;
+  esac
+done
+
+# Query specific agent or hierarchy
+if [[ -n "$AGENT_ID" ]]; then
+  # Query specific agent status
+  API_URL="http://localhost:$PORT/api/agents/$AGENT_ID/status"
+
+  RESPONSE=$(curl -f -s "$API_URL" 2>/dev/null) || {
+    echo "{\"success\":false,\"error\":\"Failed to query agent $AGENT_ID at $API_URL\"}" >&2
+    exit 1
+  }
+
+  # Validate response
+  if ! echo "$RESPONSE" | jq empty 2>/dev/null; then
+    echo "{\"success\":false,\"error\":\"Invalid JSON response from agents API\"}" >&2
+    exit 1
+  fi
+
+  # Output based on format
+  if [[ "$FORMAT" == "table" ]]; then
+    echo "$RESPONSE" | jq -r '
+      "=== Agent \(.data.id) ===",
+      "Status: \(.data.status)",
+      "Type: \(.data.type // "unknown")",
+      "Confidence: \(.data.confidence // "N/A")",
+      "Uptime: \(.data.uptime // "N/A")",
+      "",
+      "=== Metrics ===",
+      (.data.metrics // {} | to_entries | .[] | "\(.key): \(.value)")
+    ' 2>/dev/null || echo "$RESPONSE"
+  else
+    echo "$RESPONSE"
+  fi
+else
+  # Query agent hierarchy with filters
+  API_URL="http://localhost:$PORT/api/agents/hierarchy"
+  QUERY_PARAMS=""
+
+  if [[ -n "$STATUS_FILTER" || -n "$TYPE_FILTER" ]]; then
+    QUERY_PARAMS="?"
+    [[ -n "$STATUS_FILTER" ]] && QUERY_PARAMS="${QUERY_PARAMS}status=${STATUS_FILTER}&"
+    [[ -n "$TYPE_FILTER" ]] && QUERY_PARAMS="${QUERY_PARAMS}type=${TYPE_FILTER}&"
+    QUERY_PARAMS="${QUERY_PARAMS%&}"
+  fi
+
+  FULL_URL="${API_URL}${QUERY_PARAMS}"
+
+  RESPONSE=$(curl -f -s "$FULL_URL" 2>/dev/null) || {
+    echo "{\"success\":false,\"error\":\"Failed to query agents hierarchy at $FULL_URL\"}" >&2
+    exit 1
+  }
+
+  # Validate response
+  if ! echo "$RESPONSE" | jq empty 2>/dev/null; then
+    echo "{\"success\":false,\"error\":\"Invalid JSON response from agents API\"}" >&2
+    exit 1
+  fi
+
+  # Filter by swarm if requested
+  if [[ -n "$SWARM_FILTER" ]]; then
+    RESPONSE=$(echo "$RESPONSE" | jq --arg swarm "$SWARM_FILTER" '{
+      success: true,
+      data: [.data[] | select(.swarmId == $swarm)]
+    }')
+  fi
+
+  # Output based on format
+  if [[ "$FORMAT" == "table" ]]; then
+    echo "$RESPONSE" | jq -r '
+      "=== Agent Hierarchy ===",
+      "Total Agents: \(.data | length)",
+      "",
+      (.data[] | "- \(.id) (\(.status)) - Type: \(.type // "unknown") - Confidence: \(.confidence // "N/A")")
+    ' 2>/dev/null || echo "$RESPONSE"
+  else
+    echo "$RESPONSE"
+  fi
+fi

package/claude-assets/cfn-extras/skills/ui-portal/cfn-web-portal/invoke-portal-dashboard.sh

@@ -0,0 +1,85 @@
+#!/usr/bin/env bash
+# Web Portal Skill - Query Dashboard Summary
+# Usage: ./invoke-portal-dashboard.sh [--port PORT] [--format json|table]
+#
+# Fetches dashboard summary with active agents, system health, events, and performance
+
+set -euo pipefail
+
+# Configuration
+DEFAULT_PORT=3000
+DEFAULT_FORMAT="json"
+
+# Parse arguments
+PORT="$DEFAULT_PORT"
+FORMAT="$DEFAULT_FORMAT"
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --port)
+      PORT="$2"
+      shift 2
+      ;;
+    --format)
+      FORMAT="$2"
+      shift 2
+      ;;
+    *)
+      echo "Unknown argument: $1" >&2
+      exit 1
+      ;;
+  esac
+done
+
+# Query metrics API (serves as dashboard summary)
+API_URL="http://localhost:$PORT/api/metrics"
+
+# Query API
+RESPONSE=$(curl -f -s "$API_URL" 2>/dev/null) || {
+  echo "{\"success\":false,\"error\":\"Failed to query dashboard API at $API_URL\"}" >&2
+  exit 1
+}
+
+# Validate response
+if ! echo "$RESPONSE" | jq empty 2>/dev/null; then
+  echo "{\"success\":false,\"error\":\"Invalid JSON response from dashboard API\"}" >&2
+  exit 1
+fi
+
+# Also query agent hierarchy for active agents count
+AGENTS_URL="http://localhost:$PORT/api/agents/hierarchy"
+AGENTS_RESPONSE=$(curl -f -s "$AGENTS_URL" 2>/dev/null) || {
+  AGENTS_RESPONSE="{\"data\":[]}"
+}
+
+# Count active agents
+ACTIVE_AGENTS=$(echo "$AGENTS_RESPONSE" | jq -r '[.data[] | select(.status == "active")] | length' 2>/dev/null || echo "0")
+
+# Combine dashboard data
+DASHBOARD=$(jq -n \
+  --argjson metrics "$RESPONSE" \
+  --argjson activeAgents "$ACTIVE_AGENTS" \
+  '{
+    success: true,
+    dashboard: {
+      activeAgents: $activeAgents,
+      systemHealth: ($metrics.data.systemHealth // "unknown"),
+      metrics: $metrics.data,
+      timestamp: (now | strftime("%Y-%m-%dT%H:%M:%SZ"))
+    }
+  }')
+
+# Output based on format
+if [[ "$FORMAT" == "table" ]]; then
+  echo "$DASHBOARD" | jq -r '
+    "=== Dashboard Summary ===",
+    "Active Agents: \(.dashboard.activeAgents)",
+    "System Health: \(.dashboard.systemHealth)",
+    "Timestamp: \(.dashboard.timestamp)",
+    "",
+    "=== Metrics ===",
+    (.dashboard.metrics | to_entries | .[] | "\(.key): \(.value)")
+  ' 2>/dev/null || echo "$DASHBOARD"
+else
+  echo "$DASHBOARD"
+fi

package/claude-assets/cfn-extras/skills/ui-portal/cfn-web-portal/invoke-portal-events.sh

@@ -0,0 +1,125 @@
+#!/usr/bin/env bash
+# Web Portal Skill - Query Events Timeline
+# Usage: ./invoke-portal-events.sh [--type TYPE] [--agent AGENT_ID] [--phase PHASE_ID] [--since TIMESTAMP] [--severity LEVEL] [--limit NUM] [--offset NUM] [--format json|table]
+#
+# Queries /api/events timeline with filters and pagination
+
+set -euo pipefail
+
+# Configuration
+DEFAULT_PORT=3000
+DEFAULT_FORMAT="json"
+DEFAULT_LIMIT=50
+
+# Parse arguments
+PORT="$DEFAULT_PORT"
+FORMAT="$DEFAULT_FORMAT"
+TYPE_FILTER=""
+AGENT_FILTER=""
+PHASE_FILTER=""
+SINCE=""
+SEVERITY=""
+LIMIT="$DEFAULT_LIMIT"
+OFFSET=0
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --port)
+      PORT="$2"
+      shift 2
+      ;;
+    --format)
+      FORMAT="$2"
+      shift 2
+      ;;
+    --type)
+      TYPE_FILTER="$2"
+      shift 2
+      ;;
+    --agent)
+      AGENT_FILTER="$2"
+      shift 2
+      ;;
+    --phase)
+      PHASE_FILTER="$2"
+      shift 2
+      ;;
+    --since)
+      SINCE="$2"
+      shift 2
+      ;;
+    --severity)
+      SEVERITY="$2"
+      shift 2
+      ;;
+    --limit)
+      LIMIT="$2"
+      shift 2
+      ;;
+    --offset)
+      OFFSET="$2"
+      shift 2
+      ;;
+    *)
+      echo "Unknown argument: $1" >&2
+      exit 1
+      ;;
+  esac
+done
+
+# Determine API endpoint based on filters
+if [[ -n "$PHASE_FILTER" ]]; then
+  # Query by phase
+  API_URL="http://localhost:$PORT/api/events/phase/$PHASE_FILTER"
+  QUERY_PARAMS="?limit=$LIMIT"
+elif [[ -n "$AGENT_FILTER" ]]; then
+  # Query by agent
+  API_URL="http://localhost:$PORT/api/events/agent/$AGENT_FILTER"
+  QUERY_PARAMS="?limit=$LIMIT"
+else
+  # General query with filters
+  API_URL="http://localhost:$PORT/api/events"
+  QUERY_PARAMS="?limit=$LIMIT&offset=$OFFSET"
+
+  [[ -n "$TYPE_FILTER" ]] && QUERY_PARAMS="${QUERY_PARAMS}&eventType=${TYPE_FILTER}"
+  [[ -n "$SINCE" ]] && QUERY_PARAMS="${QUERY_PARAMS}&startDate=${SINCE}"
+fi
+
+FULL_URL="${API_URL}${QUERY_PARAMS}"
+
+# Query API
+RESPONSE=$(curl -f -s "$FULL_URL" 2>/dev/null) || {
+  echo "{\"success\":false,\"error\":\"Failed to query events API at $FULL_URL\"}" >&2
+  exit 1
+}
+
+# Validate response
+if ! echo "$RESPONSE" | jq empty 2>/dev/null; then
+  echo "{\"success\":false,\"error\":\"Invalid JSON response from events API\"}" >&2
+  exit 1
+fi
+
+# Apply severity filter if provided (client-side filtering)
+if [[ -n "$SEVERITY" ]]; then
+  RESPONSE=$(echo "$RESPONSE" | jq --arg sev "$SEVERITY" '{
+    success: .success,
+    data: [.data[]? | select(.metadata.severity == $sev or .severity == $sev)]
+  }')
+fi
+
+# Output based on format
+if [[ "$FORMAT" == "table" ]]; then
+  echo "$RESPONSE" | jq -r '
+    if .data then
+      "=== Events Timeline ===",
+      "Total Events: \(.data | length)",
+      "",
+      (.data[] | "[\(.timestamp // .createdAt)] \(.eventType) - Agent: \(.agentId) - Phase: \(.phaseId)")
+    else
+      "=== Events Timeline ===",
+      "No events found"
+    end
+  ' 2>/dev/null || echo "$RESPONSE"
+else
+  echo "$RESPONSE"
+fi

package/claude-assets/cfn-extras/skills/ui-portal/cfn-web-portal/invoke-portal-metrics.sh

@@ -0,0 +1,112 @@
+#!/usr/bin/env bash
+# Web Portal Skill - Query Metrics API
+# Usage: ./invoke-portal-metrics.sh [--agent AGENT_ID] [--timeframe TIMEFRAME] [--view VIEW] [--format json|table]
+#
+# Queries the /api/metrics endpoint with optional filters
+# Implements 60-second cache TTL
+
+set -euo pipefail
+
+# Configuration
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/.claude/skills/cfn-cfn-.claude/skills/cfn-cfn-.." && pwd)"
+CACHE_DIR="$PROJECT_ROOT/.artifacts/cache/web-portal"
+CACHE_TTL=60
+DEFAULT_PORT=3000
+DEFAULT_FORMAT="json"
+
+# Parse arguments
+AGENT_FILTER=""
+TIMEFRAME=""
+VIEW=""
+FORMAT="$DEFAULT_FORMAT"
+PORT="$DEFAULT_PORT"
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --agent)
+      AGENT_FILTER="$2"
+      shift 2
+      ;;
+    --timeframe)
+      TIMEFRAME="$2"
+      shift 2
+      ;;
+    --view)
+      VIEW="$2"
+      shift 2
+      ;;
+    --format)
+      FORMAT="$2"
+      shift 2
+      ;;
+    --port)
+      PORT="$2"
+      shift 2
+      ;;
+    *)
+      echo "Unknown argument: $1" >&2
+      exit 1
+      ;;
+  esac
+done
+
+# Create cache directory
+mkdir -p "$CACHE_DIR"
+
+# Generate cache key based on filters
+CACHE_KEY="metrics"
+[[ -n "$AGENT_FILTER" ]] && CACHE_KEY="${CACHE_KEY}_agent_${AGENT_FILTER}"
+[[ -n "$TIMEFRAME" ]] && CACHE_KEY="${CACHE_KEY}_time_${TIMEFRAME}"
+[[ -n "$VIEW" ]] && CACHE_KEY="${CACHE_KEY}_view_${VIEW}"
+CACHE_FILE="$CACHE_DIR/${CACHE_KEY}.json"
+
+# Check cache validity
+if [[ -f "$CACHE_FILE" ]]; then
+  CACHE_AGE=$(($(date +%s) - $(stat -c %Y "$CACHE_FILE" 2>/dev/null || stat -f %m "$CACHE_FILE" 2>/dev/null)))
+
+  if [[ $CACHE_AGE -lt $CACHE_TTL ]]; then
+    if [[ "$FORMAT" == "table" ]]; then
+      jq -r '.data | to_entries | .[] | "\(.key): \(.value)"' "$CACHE_FILE" 2>/dev/null || cat "$CACHE_FILE"
+    else
+      cat "$CACHE_FILE"
+    fi
+    exit 0
+  fi
+fi
+
+# Build API URL with query parameters
+API_URL="http://localhost:$PORT/api/metrics"
+QUERY_PARAMS=""
+
+if [[ -n "$AGENT_FILTER" || -n "$TIMEFRAME" || -n "$VIEW" ]]; then
+  QUERY_PARAMS="?"
+  [[ -n "$AGENT_FILTER" ]] && QUERY_PARAMS="${QUERY_PARAMS}agent=${AGENT_FILTER}&"
+  [[ -n "$TIMEFRAME" ]] && QUERY_PARAMS="${QUERY_PARAMS}timeframe=${TIMEFRAME}&"
+  [[ -n "$VIEW" ]] && QUERY_PARAMS="${QUERY_PARAMS}view=${VIEW}&"
+  QUERY_PARAMS="${QUERY_PARAMS%&}"
+fi
+
+FULL_URL="${API_URL}${QUERY_PARAMS}"
+
+# Query API
+RESPONSE=$(curl -f -s "$FULL_URL" 2>/dev/null) || {
+  echo "{\"success\":false,\"error\":\"Failed to query metrics API at $FULL_URL\"}" >&2
+  exit 1
+}
+
+# Validate response
+if ! echo "$RESPONSE" | jq empty 2>/dev/null; then
+  echo "{\"success\":false,\"error\":\"Invalid JSON response from metrics API\"}" >&2
+  exit 1
+fi
+
+# Store in cache
+echo "$RESPONSE" > "$CACHE_FILE"
+
+# Output based on format
+if [[ "$FORMAT" == "table" ]]; then
+  echo "$RESPONSE" | jq -r '.data | to_entries | .[] | "\(.key): \(.value)"' 2>/dev/null || echo "$RESPONSE"
+else
+  echo "$RESPONSE"
+fi

package/claude-assets/cfn-extras/skills/ui-portal/cfn-web-portal/invoke-portal-start.sh

@@ -0,0 +1,135 @@
+#!/usr/bin/env bash
+# Web Portal Skill - Start Web Portal Server
+# Usage: ./invoke-portal-start.sh [--port PORT] [--production]
+#
+# Starts the web portal server with health check validation
+# Returns: JSON with server URL, status, and health check results
+
+set -euo pipefail
+
+# Configuration
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/.claude/skills/cfn-cfn-.claude/skills/cfn-cfn-.." && pwd)"
+WEB_PORTAL_DIR="$PROJECT_ROOT/packages/web-portal"
+DEFAULT_PORT=3000
+MAX_HEALTH_CHECK_ATTEMPTS=30
+HEALTH_CHECK_INTERVAL=1
+
+# Parse arguments
+PORT="$DEFAULT_PORT"
+PRODUCTION_MODE=false
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --port)
+      PORT="$2"
+      shift 2
+      ;;
+    --production)
+      PRODUCTION_MODE=true
+      shift
+      ;;
+    *)
+      echo "Unknown argument: $1" >&2
+      exit 1
+      ;;
+  esac
+done
+
+# Validate web portal directory exists
+if [[ ! -d "$WEB_PORTAL_DIR" ]]; then
+  echo "{\"success\":false,\"error\":\"Web portal directory not found: $WEB_PORTAL_DIR\"}" >&2
+  exit 1
+fi
+
+# Kill any existing processes on the target port
+if lsof -ti:"$PORT" &>/dev/null; then
+  echo "Killing existing process on port $PORT..." >&2
+  lsof -ti:"$PORT" | xargs -r kill -9 || true
+  sleep 2
+fi
+
+# Start the server
+cd "$WEB_PORTAL_DIR"
+
+if [[ "$PRODUCTION_MODE" == "true" ]]; then
+  # Production mode: build and start
+  echo "Building for production..." >&2
+  npm run build &>/dev/null || {
+    echo "{\"success\":false,\"error\":\"Build failed\"}" >&2
+    exit 1
+  }
+
+  PORT="$PORT" npm run start &>/dev/null &
+  SERVER_PID=$!
+else
+  # Development mode: start dev server
+  echo "Starting development server on port $PORT..." >&2
+  PORT="$PORT" npm run dev &>/dev/null &
+  SERVER_PID=$!
+fi
+
+# Store PID for cleanup
+echo "$SERVER_PID" > "$WEB_PORTAL_DIR/.portal.pid"
+
+# Health check loop
+HEALTH_CHECK_URL="http://localhost:$PORT/health"
+ATTEMPTS=0
+HEALTHY=false
+
+echo "Waiting for server to be healthy..." >&2
+while [[ $ATTEMPTS -lt $MAX_HEALTH_CHECK_ATTEMPTS ]]; do
+  if curl -f -s "$HEALTH_CHECK_URL" &>/dev/null; then
+    HEALTHY=true
+    break
+  fi
+
+  ATTEMPTS=$((ATTEMPTS + 1))
+  sleep "$HEALTH_CHECK_INTERVAL"
+done
+
+# Check Redis connection
+REDIS_CONNECTED=false
+if redis-cli ping &>/dev/null; then
+  REDIS_CONNECTED=true
+fi
+
+# Construct response
+if [[ "$HEALTHY" == "true" ]]; then
+  cat <<EOF
+{
+  "success": true,
+  "serverUrl": "http://localhost:$PORT",
+  "port": $PORT,
+  "pid": $SERVER_PID,
+  "mode": "$(if [[ "$PRODUCTION_MODE" == "true" ]]; then echo "production"; else echo "development"; fi)",
+  "health": {
+    "status": "healthy",
+    "redis": $REDIS_CONNECTED,
+    "uptime": 0,
+    "checks": $ATTEMPTS
+  },
+  "endpoints": {
+    "api": "http://localhost:$PORT/api",
+    "metrics": "http://localhost:$PORT/api/metrics",
+    "agents": "http://localhost:$PORT/api/agents",
+    "events": "http://localhost:$PORT/api/events",
+    "health": "http://localhost:$PORT/health"
+  }
+}
+EOF
+else
+  # Server failed to start
+  kill "$SERVER_PID" &>/dev/null || true
+  rm -f "$WEB_PORTAL_DIR/.portal.pid"
+
+  cat <<EOF >&2
+{
+  "success": false,
+  "error": "Server failed health check after $MAX_HEALTH_CHECK_ATTEMPTS attempts",
+  "port": $PORT,
+  "redisConnected": $REDIS_CONNECTED
+}
+EOF
+  exit 1
+fi

package/claude-assets/cfn-extras/skills/ui-portal/cfn-web-portal/invoke-portal-stop.sh

@@ -0,0 +1,121 @@
+#!/usr/bin/env bash
+# Web Portal Skill - Stop Web Portal Server
+# Usage: ./invoke-portal-stop.sh [--port PORT] [--force]
+#
+# Gracefully stops the web portal server with cleanup
+
+set -euo pipefail
+
+# Configuration
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/.claude/skills/cfn-cfn-.claude/skills/cfn-cfn-.." && pwd)"
+WEB_PORTAL_DIR="$PROJECT_ROOT/packages/web-portal"
+DEFAULT_PORT=3000
+SHUTDOWN_TIMEOUT=10
+
+# Parse arguments
+PORT="$DEFAULT_PORT"
+FORCE_SHUTDOWN=false
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --port)
+      PORT="$2"
+      shift 2
+      ;;
+    --force)
+      FORCE_SHUTDOWN=true
+      shift
+      ;;
+    *)
+      echo "Unknown argument: $1" >&2
+      exit 1
+      ;;
+  esac
+done
+
+# Check for PID file
+PID_FILE="$WEB_PORTAL_DIR/.portal.pid"
+SERVER_PID=""
+
+if [[ -f "$PID_FILE" ]]; then
+  SERVER_PID=$(cat "$PID_FILE" 2>/dev/null || echo "")
+fi
+
+# Try graceful shutdown first (if server has /api/shutdown endpoint)
+if [[ "$FORCE_SHUTDOWN" == "false" ]]; then
+  SHUTDOWN_URL="http://localhost:$PORT/api/shutdown"
+
+  if curl -f -s -X POST "$SHUTDOWN_URL" &>/dev/null; then
+    echo "Graceful shutdown initiated via API..." >&2
+
+    # Wait for server to stop
+    WAIT_TIME=0
+    while [[ $WAIT_TIME -lt $SHUTDOWN_TIMEOUT ]]; do
+      if ! curl -f -s "http://localhost:$PORT/health" &>/dev/null; then
+        break
+      fi
+
+      sleep 1
+      WAIT_TIME=$((WAIT_TIME + 1))
+    done
+  fi
+fi
+
+# Check if server is still running
+SERVER_RUNNING=false
+if curl -f -s "http://localhost:$PORT/health" &>/dev/null; then
+  SERVER_RUNNING=true
+fi
+
+# Force kill if still running
+if [[ "$SERVER_RUNNING" == "true" ]]; then
+  echo "Forcing server shutdown..." >&2
+
+  # Kill by PID file
+  if [[ -n "$SERVER_PID" ]] && kill -0 "$SERVER_PID" 2>/dev/null; then
+    kill -TERM "$SERVER_PID" 2>/dev/null || true
+    sleep 2
+
+    if kill -0 "$SERVER_PID" 2>/dev/null; then
+      kill -KILL "$SERVER_PID" 2>/dev/null || true
+    fi
+  fi
+
+  # Kill by port
+  if lsof -ti:"$PORT" &>/dev/null; then
+    lsof -ti:"$PORT" | xargs -r kill -TERM 2>/dev/null || true
+    sleep 2
+
+    if lsof -ti:"$PORT" &>/dev/null; then
+      lsof -ti:"$PORT" | xargs -r kill -KILL 2>/dev/null || true
+    fi
+  fi
+fi
+
+# Cleanup PID file
+if [[ -f "$PID_FILE" ]]; then
+  rm -f "$PID_FILE"
+fi
+
+# Verify server is stopped
+if curl -f -s "http://localhost:$PORT/health" &>/dev/null; then
+  cat <<EOF >&2
+{
+  "success": false,
+  "error": "Failed to stop server on port $PORT",
+  "port": $PORT
+}
+EOF
+  exit 1
+else
+  cat <<EOF
+{
+  "success": true,
+  "message": "Web portal server stopped successfully",
+  "port": $PORT,
+  "pid": ${SERVER_PID:-"unknown"},
+  "method": "$(if [[ "$FORCE_SHUTDOWN" == "true" ]]; then echo "forced"; else echo "graceful"; fi)"
+}
+EOF
+fi