Initial commit

.claude-plugin/plugin.json

@@ -0,0 +1,15 @@
+{
+  "name": "websocket-server-builder",
+  "description": "Build WebSocket servers for real-time bidirectional communication",
+  "version": "1.0.0",
+  "author": {
+    "name": "Jeremy Longshore",
+    "email": "[email protected]"
+  },
+  "skills": [
+    "./skills"
+  ],
+  "commands": [
+    "./commands"
+  ]
+}

README.md

@@ -0,0 +1,3 @@
+# websocket-server-builder
+
+Build WebSocket servers for real-time bidirectional communication

plugin.lock.json

@@ -0,0 +1,97 @@
+{
+  "$schema": "internal://schemas/plugin.lock.v1.json",
+  "pluginId": "gh:jeremylongshore/claude-code-plugins-plus:plugins/api-development/websocket-server-builder",
+  "normalized": {
+    "repo": null,
+    "ref": "refs/tags/v20251128.0",
+    "commit": "f1e4c551348bc9ad6656e442a3b312c518550a85",
+    "treeHash": "80529f219b7667550df4e566974c5ce80a5575443cba3b8c8c012241177a0f49",
+    "generatedAt": "2025-11-28T10:18:52.568912Z",
+    "toolVersion": "publish_plugins.py@0.2.0"
+  },
+  "origin": {
+    "remote": "git@github.com:zhongweili/42plugin-data.git",
+    "branch": "master",
+    "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390",
+    "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data"
+  },
+  "manifest": {
+    "name": "websocket-server-builder",
+    "description": "Build WebSocket servers for real-time bidirectional communication",
+    "version": "1.0.0"
+  },
+  "content": {
+    "files": [
+      {
+        "path": "README.md",
+        "sha256": "392ae10aeb439ac36398ede716e1d1e66f5c4529633bf17ec2ea095da47dfcde"
+      },
+      {
+        "path": ".claude-plugin/plugin.json",
+        "sha256": "1960a5f2d47aaef61534da08fe02b3adcc4fecd1217f9e8625c89ad4533785cf"
+      },
+      {
+        "path": "commands/build-websocket-server.md",
+        "sha256": "55134ffacbd862229789ffe5ac45d876fd6a241a56cb5f81bc9501fd71fa151e"
+      },
+      {
+        "path": "skills/skill-adapter/references/examples.md",
+        "sha256": "922bbc3c4ebf38b76f515b5c1998ebde6bf902233e00e2c5a0e9176f975a7572"
+      },
+      {
+        "path": "skills/skill-adapter/references/best-practices.md",
+        "sha256": "c8f32b3566252f50daacd346d7045a1060c718ef5cfb07c55a0f2dec5f1fb39e"
+      },
+      {
+        "path": "skills/skill-adapter/references/README.md",
+        "sha256": "dd0333d5049c487e017cf189a6a2fdcd52729af1c722d2e68239cfc4d1ad2b37"
+      },
+      {
+        "path": "skills/skill-adapter/scripts/helper-template.sh",
+        "sha256": "0881d5660a8a7045550d09ae0acc15642c24b70de6f08808120f47f86ccdf077"
+      },
+      {
+        "path": "skills/skill-adapter/scripts/validation.sh",
+        "sha256": "92551a29a7f512d2036e4f1fb46c2a3dc6bff0f7dde4a9f699533e446db48502"
+      },
+      {
+        "path": "skills/skill-adapter/scripts/README.md",
+        "sha256": "e9e92b95cdb48fe1363512c6354191e5d48b73512a8d261f4f6181b3bb5971d5"
+      },
+      {
+        "path": "skills/skill-adapter/assets/test-data.json",
+        "sha256": "ac17dca3d6e253a5f39f2a2f1b388e5146043756b05d9ce7ac53a0042eee139d"
+      },
+      {
+        "path": "skills/skill-adapter/assets/template_socketio.py",
+        "sha256": "4e4813eb9eeac78fa0660891acbe8cc03372538940ec3c28dc610cb0350d25c2"
+      },
+      {
+        "path": "skills/skill-adapter/assets/README.md",
+        "sha256": "bd460681d5a2b485922b9dabc46750c09a7c9cf0e4dac663fa34353f1d7abe23"
+      },
+      {
+        "path": "skills/skill-adapter/assets/template_native_ws.py",
+        "sha256": "d00dc10c215c0d53125f8528c6ccdccd4b2f966dd02cef15ff3f8ed0e22c8011"
+      },
+      {
+        "path": "skills/skill-adapter/assets/skill-schema.json",
+        "sha256": "f5639ba823a24c9ac4fb21444c0717b7aefde1a4993682897f5bf544f863c2cd"
+      },
+      {
+        "path": "skills/skill-adapter/assets/example_client.html",
+        "sha256": "19eb22fadc64f533757fc45e3c3db67d321dea349f20e1951a7b8620883d248f"
+      },
+      {
+        "path": "skills/skill-adapter/assets/config-template.json",
+        "sha256": "0c2ba33d2d3c5ccb266c0848fc43caa68a2aa6a80ff315d4b378352711f83e1c"
+      }
+    ],
+    "dirSha256": "80529f219b7667550df4e566974c5ce80a5575443cba3b8c8c012241177a0f49"
+  },
+  "security": {
+    "scannedAt": null,
+    "scannerVersion": null,
+    "flags": []
+  }
+}

skills/skill-adapter/assets/README.md

@@ -0,0 +1,7 @@
+# Assets
+
+Bundled resources for websocket-server-builder skill
+
+- [ ] template_socketio.py: Template file for a basic WebSocket server using Socket.IO.
+- [ ] template_native_ws.py: Template file for a basic WebSocket server using native WebSockets.
+- [ ] example_client.html: Example HTML client for testing the WebSocket server.

skills/skill-adapter/assets/config-template.json

@@ -0,0 +1,32 @@
+{
+  "skill": {
+    "name": "skill-name",
+    "version": "1.0.0",
+    "enabled": true,
+    "settings": {
+      "verbose": false,
+      "autoActivate": true,
+      "toolRestrictions": true
+    }
+  },
+  "triggers": {
+    "keywords": [
+      "example-trigger-1",
+      "example-trigger-2"
+    ],
+    "patterns": []
+  },
+  "tools": {
+    "allowed": [
+      "Read",
+      "Grep",
+      "Bash"
+    ],
+    "restricted": []
+  },
+  "metadata": {
+    "author": "Plugin Author",
+    "category": "general",
+    "tags": []
+  }
+}

skills/skill-adapter/assets/example_client.html

@@ -0,0 +1,140 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>WebSocket Client Example</title>
+    <style>
+        /* Basic Styling */
+        body {
+            font-family: sans-serif;
+            margin: 0;
+            padding: 0;
+            background-color: #f4f4f4;
+            display: flex;
+            justify-content: center;
+            align-items: center;
+            min-height: 100vh;
+        }
+
+        .container {
+            width: 80%;
+            max-width: 600px;
+            background-color: #fff;
+            padding: 20px;
+            border-radius: 8px;
+            box-shadow: 0 2px 4px rgba(0, 0, 0, 0.1);
+            text-align: center;
+        }
+
+        h1 {
+            color: #333;
+        }
+
+        #messages {
+            margin-top: 20px;
+            text-align: left;
+        }
+
+        #message-input {
+            width: 70%;
+            padding: 10px;
+            margin-right: 10px;
+            border: 1px solid #ccc;
+            border-radius: 4px;
+        }
+
+        #send-button {
+            padding: 10px 20px;
+            background-color: #007bff;
+            color: white;
+            border: none;
+            border-radius: 4px;
+            cursor: pointer;
+        }
+
+        #send-button:hover {
+            background-color: #0056b3;
+        }
+
+        /* Responsive Design */
+        @media (max-width: 600px) {
+            .container {
+                width: 95%;
+            }
+
+            #message-input {
+                width: 60%;
+            }
+        }
+    </style>
+</head>
+<body>
+    <div class="container">
+        <h1>WebSocket Client</h1>
+        <p>Connect to WebSocket server at: <code>{{websocket_url}}</code></p>
+
+        <div id="messages">
+            <!-- Messages will be displayed here -->
+        </div>
+
+        <div>
+            <input type="text" id="message-input" placeholder="Enter message">
+            <button id="send-button">Send</button>
+        </div>
+    </div>
+
+    <script>
+        // JavaScript to handle WebSocket connection and messages
+        const websocketUrl = "{{websocket_url}}"; // Replace with your WebSocket server URL
+        const messagesDiv = document.getElementById('messages');
+        const messageInput = document.getElementById('message-input');
+        const sendButton = document.getElementById('send-button');
+
+        let websocket;
+
+        function connectWebSocket() {
+            websocket = new WebSocket(websocketUrl);
+
+            websocket.onopen = () => {
+                console.log('Connected to WebSocket server');
+                appendMessage('Connected to server.');
+            };
+
+            websocket.onmessage = (event) => {
+                console.log('Received message:', event.data);
+                appendMessage('Server: ' + event.data);
+            };
+
+            websocket.onclose = () => {
+                console.log('Disconnected from WebSocket server');
+                appendMessage('Disconnected from server.');
+            };
+
+            websocket.onerror = (error) => {
+                console.error('WebSocket error:', error);
+                appendMessage('Error: ' + error);
+            };
+        }
+
+        function appendMessage(message) {
+            const messageElement = document.createElement('p');
+            messageElement.textContent = message;
+            messagesDiv.appendChild(messageElement);
+            messagesDiv.scrollTop = messagesDiv.scrollHeight; // Auto-scroll to bottom
+        }
+
+        sendButton.addEventListener('click', () => {
+            const message = messageInput.value;
+            if (message) {
+                websocket.send(message);
+                appendMessage('You: ' + message);
+                messageInput.value = ''; // Clear the input
+            }
+        });
+
+        // Connect to the WebSocket server when the page loads
+        connectWebSocket();
+    </script>
+</body>
+</html>

skills/skill-adapter/assets/skill-schema.json

@@ -0,0 +1,28 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Claude Skill Configuration",
+  "type": "object",
+  "required": ["name", "description"],
+  "properties": {
+    "name": {
+      "type": "string",
+      "pattern": "^[a-z0-9-]+$",
+      "maxLength": 64,
+      "description": "Skill identifier (lowercase, hyphens only)"
+    },
+    "description": {
+      "type": "string",
+      "maxLength": 1024,
+      "description": "What the skill does and when to use it"
+    },
+    "allowed-tools": {
+      "type": "string",
+      "description": "Comma-separated list of allowed tools"
+    },
+    "version": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+$",
+      "description": "Semantic version (x.y.z)"
+    }
+  }
+}

skills/skill-adapter/assets/template_native_ws.py

@@ -0,0 +1,75 @@
+#!/usr/bin/env python3
+
+"""
+Template for a basic WebSocket server using native WebSockets.
+
+This script provides a foundation for building real-time bidirectional
+communication applications using Python's built-in `websockets` library.
+It includes basic connection handling, message reception, and sending.
+
+Example usage:
+1. Install the `websockets` library: `pip install websockets`
+2. Run the script: `python template_native_ws.py`
+3. Connect to the server using a WebSocket client (e.g., a browser-based client).
+"""
+
+import asyncio
+import websockets
+import logging
+
+# Configure logging
+logging.basicConfig(level=logging.INFO)
+
+
+async def handle_client(websocket, path):
+    """
+    Handles a single WebSocket client connection.
+
+    Args:
+        websocket: The WebSocket connection object.
+        path: The path requested by the client (unused in this example).
+    """
+    try:
+        logging.info(f"Client connected from {websocket.remote_address}")
+        async for message in websocket:
+            logging.info(f"Received message: {message}")
+            try:
+                # Process the message (replace with your application logic)
+                response = f"Server received: {message}"
+                await websocket.send(response)
+                logging.info(f"Sent message: {response}")
+            except Exception as e:
+                logging.error(f"Error processing message: {e}")
+                await websocket.send(f"Error: {e}")
+
+    except websockets.exceptions.ConnectionClosedError as e:
+        logging.info(f"Client disconnected abruptly: {e}")
+    except websockets.exceptions.ConnectionClosedOK as e:
+        logging.info(f"Client disconnected gracefully: {e}")
+    except Exception as e:
+        logging.error(f"Error handling client: {e}")
+    finally:
+        logging.info(f"Connection with {websocket.remote_address} closed.")
+
+
+async def main():
+    """
+    Starts the WebSocket server.
+    """
+    try:
+        server = await websockets.serve(handle_client, "localhost", 8765)
+        logging.info("WebSocket server started on ws://localhost:8765")
+        await server.wait_closed()
+    except OSError as e:
+        logging.error(f"Could not start server: {e}")
+    except Exception as e:
+        logging.error(f"Unexpected error: {e}")
+
+
+if __name__ == "__main__":
+    try:
+        asyncio.run(main())
+    except KeyboardInterrupt:
+        logging.info("Server stopped by keyboard interrupt.")
+    except Exception as e:
+        logging.error(f"Unhandled exception during server startup: {e}")

skills/skill-adapter/assets/template_socketio.py

@@ -0,0 +1,156 @@
+#!/usr/bin/env python3
+"""
+Template for a basic WebSocket server using Socket.IO.
+
+This script provides a foundation for building real-time bidirectional
+communication applications. It includes error handling, example usage,
+and follows PEP 8 style guidelines.
+"""
+
+import os
+import logging
+import socketio
+from aiohttp import web
+
+# Configure logging
+logging.basicConfig(level=logging.INFO,
+                    format='%(asctime)s - %(levelname)s - %(message)s')
+
+# Initialize Socket.IO server
+sio = socketio.AsyncServer(async_mode='aiohttp', cors_allowed_origins='*')
+
+# Create AIOHTTP application
+app = web.Application()
+
+# Bind Socket.IO to the application
+sio.attach(app)
+
+# Define event handlers
+@sio.event
+async def connect(sid, environ):
+    """
+    Handles a new client connection.
+
+    Args:
+        sid (str): Session ID of the client.
+        environ (dict): Environment variables.
+    """
+    logging.info(f"Client connected: {sid}")
+    try:
+        await sio.emit('my_response', {'data': 'Connected', 'count': 0}, room=sid)
+    except Exception as e:
+        logging.error(f"Error emitting connect message: {e}")
+
+
+@sio.event
+async def disconnect(sid):
+    """
+    Handles a client disconnection.
+
+    Args:
+        sid (str): Session ID of the client.
+    """
+    logging.info(f"Client disconnected: {sid}")
+
+
+@sio.event
+async def my_message(sid, message):
+    """
+    Handles a custom message event.
+
+    Args:
+        sid (str): Session ID of the client.
+        message (str): The received message.
+    """
+    logging.info(f"Received message from {sid}: {message}")
+    try:
+        await sio.emit('my_response', {'data': message}, room=sid)
+    except Exception as e:
+        logging.error(f"Error emitting my_response: {e}")
+
+
+@sio.event
+async def my_broadcast_event(sid, message):
+    """
+    Handles a broadcast event.
+
+    Args:
+        sid (str): Session ID of the client.
+        message (str): The message to broadcast.
+    """
+    logging.info(f"Received broadcast request from {sid}: {message}")
+    try:
+        await sio.emit('my_response', {'data': message})  # Broadcast to all clients
+    except Exception as e:
+        logging.error(f"Error emitting broadcast message: {e}")
+
+
+@sio.event
+async def join_room(sid, room):
+    """
+    Handles a request to join a room.
+
+    Args:
+        sid (str): Session ID of the client.
+        room (str): The room to join.
+    """
+    logging.info(f"Client {sid} joining room {room}")
+    try:
+        sio.enter_room(sid, room)
+        await sio.emit('my_response', {'data': 'Entered room: ' + room}, room=sid)
+    except Exception as e:
+        logging.error(f"Error joining room: {e}")
+
+
+@sio.event
+async def leave_room(sid, room):
+    """
+    Handles a request to leave a room.
+
+    Args:
+        sid (str): Session ID of the client.
+        room (str): The room to leave.
+    """
+    logging.info(f"Client {sid} leaving room {room}")
+    try:
+        sio.leave_room(sid, room)
+        await sio.emit('my_response', {'data': 'Left room: ' + room}, room=sid)
+    except Exception as e:
+        logging.error(f"Error leaving room: {e}")
+
+
+async def index(request):
+    """
+    Serves the index.html file.
+
+    Args:
+        request (aiohttp.web.Request): The request object.
+
+    Returns:
+        aiohttp.web.Response: The response object containing the HTML content.
+    """
+    try:
+        with open('index.html') as f:
+            return web.Response(content_type='text/html', text=f.read())
+    except FileNotFoundError:
+        return web.Response(status=404, text="index.html not found")
+    except Exception as e:
+        logging.error(f"Error serving index.html: {e}")
+        return web.Response(status=500, text=f"Internal Server Error: {e}")
+
+if __name__ == '__main__':
+    """
+    Main entry point of the application.
+    """
+    try:
+        # Serve static files (e.g., index.html)
+        app.router.add_get('/', index)
+        app.router.add_static('/static', './static')  # Assuming a 'static' directory
+
+        # Start the web server
+        port = int(os.environ.get('PORT', 5000))  # Default port 5000 or from environment
+        logging.info(f"Starting server on port {port}")
+        web.run_app(app, port=port)
+
+    except Exception as e:
+        logging.error(f"Failed to start the server: {e}")

skills/skill-adapter/assets/test-data.json

@@ -0,0 +1,27 @@
+{
+  "testCases": [
+    {
+      "name": "Basic activation test",
+      "input": "trigger phrase example",
+      "expected": {
+        "activated": true,
+        "toolsUsed": ["Read", "Grep"],
+        "success": true
+      }
+    },
+    {
+      "name": "Complex workflow test",
+      "input": "multi-step trigger example",
+      "expected": {
+        "activated": true,
+        "steps": 3,
+        "toolsUsed": ["Read", "Write", "Bash"],
+        "success": true
+      }
+    }
+  ],
+  "fixtures": {
+    "sampleInput": "example data",
+    "expectedOutput": "processed result"
+  }
+}

skills/skill-adapter/references/README.md

@@ -0,0 +1,8 @@
+# References
+
+Bundled resources for websocket-server-builder skill
+
+- [ ] websocket_best_practices.md: Provides best practices for building secure and scalable WebSocket servers.
+- [ ] socketio_api_reference.md: Detailed API reference for Socket.IO, if used.
+- [ ] native_ws_api_reference.md: Detailed API reference for native WebSockets, if used.
+- [ ] error_handling_guide.md: Guide to handling common WebSocket errors and exceptions.

skills/skill-adapter/references/best-practices.md

@@ -0,0 +1,69 @@
+# Skill Best Practices
+
+Guidelines for optimal skill usage and development.
+
+## For Users
+
+### Activation Best Practices
+
+1. **Use Clear Trigger Phrases**
+   - Match phrases from skill description
+   - Be specific about intent
+   - Provide necessary context
+
+2. **Provide Sufficient Context**
+   - Include relevant file paths
+   - Specify scope of analysis
+   - Mention any constraints
+
+3. **Understand Tool Permissions**
+   - Check allowed-tools in frontmatter
+   - Know what the skill can/cannot do
+   - Request appropriate actions
+
+### Workflow Optimization
+
+- Start with simple requests
+- Build up to complex workflows
+- Verify each step before proceeding
+- Use skill consistently for related tasks
+
+## For Developers
+
+### Skill Development Guidelines
+
+1. **Clear Descriptions**
+   - Include explicit trigger phrases
+   - Document all capabilities
+   - Specify limitations
+
+2. **Proper Tool Permissions**
+   - Use minimal necessary tools
+   - Document security implications
+   - Test with restricted tools
+
+3. **Comprehensive Documentation**
+   - Provide usage examples
+   - Document common pitfalls
+   - Include troubleshooting guide
+
+### Maintenance
+
+- Keep version updated
+- Test after tool updates
+- Monitor user feedback
+- Iterate on descriptions
+
+## Performance Tips
+
+- Scope skills to specific domains
+- Avoid overlapping trigger phrases
+- Keep descriptions under 1024 chars
+- Test activation reliability
+
+## Security Considerations
+
+- Never include secrets in skill files
+- Validate all inputs
+- Use read-only tools when possible
+- Document security requirements

skills/skill-adapter/references/examples.md

@@ -0,0 +1,70 @@
+# Skill Usage Examples
+
+This document provides practical examples of how to use this skill effectively.
+
+## Basic Usage
+
+### Example 1: Simple Activation
+
+**User Request:**
+```
+[Describe trigger phrase here]
+```
+
+**Skill Response:**
+1. Analyzes the request
+2. Performs the required action
+3. Returns results
+
+### Example 2: Complex Workflow
+
+**User Request:**
+```
+[Describe complex scenario]
+```
+
+**Workflow:**
+1. Step 1: Initial analysis
+2. Step 2: Data processing
+3. Step 3: Result generation
+4. Step 4: Validation
+
+## Advanced Patterns
+
+### Pattern 1: Chaining Operations
+
+Combine this skill with other tools:
+```
+Step 1: Use this skill for [purpose]
+Step 2: Chain with [other tool]
+Step 3: Finalize with [action]
+```
+
+### Pattern 2: Error Handling
+
+If issues occur:
+- Check trigger phrase matches
+- Verify context is available
+- Review allowed-tools permissions
+
+## Tips & Best Practices
+
+- ✅ Be specific with trigger phrases
+- ✅ Provide necessary context
+- ✅ Check tool permissions match needs
+- ❌ Avoid vague requests
+- ❌ Don't mix unrelated tasks
+
+## Common Issues
+
+**Issue:** Skill doesn't activate
+**Solution:** Use exact trigger phrases from description
+
+**Issue:** Unexpected results
+**Solution:** Check input format and context
+
+## See Also
+
+- Main SKILL.md for full documentation
+- scripts/ for automation helpers
+- assets/ for configuration examples

skills/skill-adapter/scripts/README.md

@@ -0,0 +1,7 @@
+# Scripts
+
+Bundled resources for websocket-server-builder skill
+
+- [ ] init_websocket_server.py: Automates the initial setup of a basic WebSocket server with Socket.IO or native WS.
+- [ ] add_route.py: Adds a new route/endpoint to the WebSocket server, handling different message types.
+- [ ] test_connection.py: Tests the WebSocket connection to ensure it's functioning correctly.

skills/skill-adapter/scripts/helper-template.sh

@@ -0,0 +1,42 @@
+#!/bin/bash
+# Helper script template for skill automation
+# Customize this for your skill's specific needs
+
+set -e
+
+function show_usage() {
+    echo "Usage: $0 [options]"
+    echo ""
+    echo "Options:"
+    echo "  -h, --help     Show this help message"
+    echo "  -v, --verbose  Enable verbose output"
+    echo ""
+}
+
+# Parse arguments
+VERBOSE=false
+
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        -h|--help)
+            show_usage
+            exit 0
+            ;;
+        -v|--verbose)
+            VERBOSE=true
+            shift
+            ;;
+        *)
+            echo "Unknown option: $1"
+            show_usage
+            exit 1
+            ;;
+    esac
+done
+
+# Your skill logic here
+if [ "$VERBOSE" = true ]; then
+    echo "Running skill automation..."
+fi
+
+echo "✅ Complete"

skills/skill-adapter/scripts/validation.sh

@@ -0,0 +1,32 @@
+#!/bin/bash
+# Skill validation helper
+# Validates skill activation and functionality
+
+set -e
+
+echo "🔍 Validating skill..."
+
+# Check if SKILL.md exists
+if [ ! -f "../SKILL.md" ]; then
+    echo "❌ Error: SKILL.md not found"
+    exit 1
+fi
+
+# Validate frontmatter
+if ! grep -q "^---$" "../SKILL.md"; then
+    echo "❌ Error: No frontmatter found"
+    exit 1
+fi
+
+# Check required fields
+if ! grep -q "^name:" "../SKILL.md"; then
+    echo "❌ Error: Missing 'name' field"
+    exit 1
+fi
+
+if ! grep -q "^description:" "../SKILL.md"; then
+    echo "❌ Error: Missing 'description' field"
+    exit 1
+fi
+
+echo "✅ Skill validation passed"