wopr-plugin-router 0.3.0

package/README.md

@@ -0,0 +1,235 @@
+# WOPR Router Plugin
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![WOPR](https://img.shields.io/badge/WOPR-Plugin-blue)](https://github.com/TSavo/wopr)
+
+A middleware plugin for [WOPR](https://github.com/TSavo/wopr) that routes messages between channels and sessions. Fan out incoming messages to multiple sessions or forward outgoing responses to specific channels.
+
+> Part of the [WOPR](https://github.com/TSavo/wopr) ecosystem - Self-sovereign AI session management over P2P.
+
+## Features
+
+- **Incoming Routes**: Fan out messages from one session to multiple target sessions
+- **Outgoing Routes**: Forward responses to specific channel types or IDs
+- **Web UI**: Built-in configuration panel integrated into WOPR settings
+- **Hot Reload**: Configuration changes apply immediately without restart
+
+## Installation
+
+Place the plugin in your WOPR plugins directory or install via npm:
+
+```bash
+npm install wopr-plugin-router
+```
+
+The plugin exports an ES module with the following interface:
+
+```javascript
+export default {
+  name: "router",
+  version: "0.1.0",
+  description: "Example routing middleware between channels and sessions",
+  init(pluginContext),
+  shutdown()
+}
+```
+
+## Configuration
+
+### Plugin Configuration
+
+Configure routes in the plugin config (stored at `plugins.data.router`):
+
+```json
+{
+  "uiPort": 7333,
+  "routes": [
+    {
+      "sourceSession": "support",
+      "targetSessions": ["billing", "engineering"],
+      "channelType": "discord",
+      "channelId": "123456789"
+    }
+  ],
+  "outgoingRoutes": [
+    {
+      "sourceSession": "support",
+      "channelType": "discord",
+      "channelId": "123456789"
+    }
+  ]
+}
+```
+
+### Configuration Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `uiPort` | number | `7333` | Port for the plugin's web UI server |
+| `routes` | array | `[]` | Incoming message routing rules |
+| `outgoingRoutes` | array | `[]` | Outgoing response routing rules |
+
+### Route Fields
+
+**Incoming Routes (`routes`):**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `sourceSession` | string | No | Match messages from this session |
+| `targetSessions` | array | Yes | Forward messages to these sessions |
+| `channelType` | string | No | Match only this channel type (e.g., "discord", "slack") |
+| `channelId` | string | No | Match only this specific channel ID |
+
+**Outgoing Routes (`outgoingRoutes`):**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `sourceSession` | string | No | Match responses from this session |
+| `channelType` | string | No | Forward only to channels of this type |
+| `channelId` | string | No | Forward only to this specific channel ID |
+
+### CLI Configuration
+
+```bash
+wopr config set plugins.data.router '{
+  "uiPort": 7333,
+  "routes": [
+    {
+      "sourceSession": "support",
+      "targetSessions": ["billing", "engineering"],
+      "channelType": "discord"
+    }
+  ],
+  "outgoingRoutes": [
+    {
+      "sourceSession": "support",
+      "channelType": "discord"
+    }
+  ]
+}'
+```
+
+### API Configuration
+
+```bash
+curl -X PUT http://localhost:7437/config/plugins.data.router \
+  -H "Content-Type: application/json" \
+  -d '{
+    "uiPort": 7333,
+    "routes": [
+      {
+        "sourceSession": "support",
+        "targetSessions": ["billing", "engineering"],
+        "channelType": "discord"
+      }
+    ],
+    "outgoingRoutes": [
+      {
+        "sourceSession": "support",
+        "channelType": "discord"
+      }
+    ]
+  }'
+```
+
+## Web UI
+
+The plugin includes a web-based configuration panel that integrates into WOPR's settings interface.
+
+- **URL**: `http://127.0.0.1:7333` (or configured `uiPort`)
+- **Location**: Appears in WOPR settings under "Message Router"
+- **Features**: Add/delete routing rules, view current configuration
+
+The UI component is built with SolidJS signals for reactive updates.
+
+## Behavior
+
+### Incoming Message Flow
+
+1. Message arrives at a session via a channel
+2. Plugin checks all `routes` for matches
+3. For each matching route, message is injected into `targetSessions`
+4. Original message continues to the source session normally
+
+**Match Logic**: A route matches if ALL specified fields match:
+- `sourceSession` matches the message's session (if specified)
+- `channelType` matches the channel's type (if specified)
+- `channelId` matches the channel's ID (if specified)
+
+### Outgoing Response Flow
+
+1. Session generates a response
+2. Plugin checks all `outgoingRoutes` for matches
+3. For each matching route, response is sent to channels connected to that session
+4. Channel filtering applies: only channels matching `channelType` and/or `channelId` receive the response
+
+## Plugin Context API
+
+The plugin uses the following WOPR plugin context methods:
+
+| Method | Description |
+|--------|-------------|
+| `ctx.getPluginDir()` | Get the plugin's directory path |
+| `ctx.getConfig()` | Get the plugin's current configuration |
+| `ctx.log.info(msg)` | Log informational messages |
+| `ctx.registerMiddleware(config)` | Register incoming/outgoing middleware |
+| `ctx.registerUiComponent(config)` | Register a UI component in WOPR |
+| `ctx.inject(session, message)` | Inject a message into a session |
+| `ctx.getChannelsForSession(session)` | Get all channel adapters for a session |
+
+## Examples
+
+### Support Ticket Routing
+
+Route customer support messages to both billing and engineering teams:
+
+```json
+{
+  "routes": [
+    {
+      "sourceSession": "support",
+      "targetSessions": ["billing", "engineering"],
+      "channelType": "discord"
+    }
+  ]
+}
+```
+
+### Channel-Specific Routing
+
+Route messages from a specific Discord channel to multiple sessions:
+
+```json
+{
+  "routes": [
+    {
+      "channelId": "1234567890",
+      "targetSessions": ["alerts", "logs", "monitoring"]
+    }
+  ]
+}
+```
+
+### Broadcast Responses
+
+Send all responses from a session to all connected Discord channels:
+
+```json
+{
+  "outgoingRoutes": [
+    {
+      "sourceSession": "announcements",
+      "channelType": "discord"
+    }
+  ]
+}
+```
+
+## Requirements
+
+- WOPR >= 1.0.0
+- Node.js (ES modules support)
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,71 @@
+/**
+ * WOPR Router Plugin
+ *
+ * Middleware-driven routing between channels and sessions.
+ */
+interface Route {
+    sourceSession?: string;
+    targetSessions?: string[];
+    channelType?: string;
+    channelId?: string;
+}
+interface OutgoingRoute {
+    sourceSession?: string;
+    channelType?: string;
+    channelId?: string;
+}
+interface RouterConfig {
+    uiPort?: number;
+    routes?: Route[];
+    outgoingRoutes?: OutgoingRoute[];
+}
+interface Channel {
+    type: string;
+    id: string;
+}
+interface ChannelAdapter {
+    channel: Channel;
+    send(message: string): Promise<void>;
+}
+interface IncomingInput {
+    session: string;
+    channel?: Channel;
+    message: string;
+}
+interface OutgoingOutput {
+    session: string;
+    response: string;
+}
+interface Logger {
+    info(message: string): void;
+    warn(message: string): void;
+    error(message: string): void;
+}
+interface UiComponentConfig {
+    id: string;
+    title: string;
+    moduleUrl: string;
+    slot: string;
+    description: string;
+}
+interface PluginContext {
+    log: Logger;
+    getConfig(): RouterConfig;
+    getPluginDir(): string;
+    inject(session: string, message: string): Promise<void>;
+    getChannelsForSession(session: string): ChannelAdapter[];
+    registerMiddleware(middleware: {
+        name: string;
+        onIncoming?(input: IncomingInput): Promise<string>;
+        onOutgoing?(output: OutgoingOutput): Promise<string>;
+    }): void;
+    registerUiComponent?(config: UiComponentConfig): void;
+}
+declare const _default: {
+    name: string;
+    version: string;
+    description: string;
+    init(pluginContext: PluginContext): Promise<void>;
+    shutdown(): Promise<void>;
+};
+export default _default;

package/dist/index.js

@@ -0,0 +1,118 @@
+/**
+ * WOPR Router Plugin
+ *
+ * Middleware-driven routing between channels and sessions.
+ */
+import http from "http";
+import { createReadStream } from "fs";
+import { extname, join } from "path";
+const CONTENT_TYPES = {
+    ".js": "application/javascript",
+    ".css": "text/css",
+    ".html": "text/html",
+};
+let ctx = null;
+let uiServer = null;
+function startUIServer(port = 7333) {
+    const server = http.createServer((req, res) => {
+        const url = req.url === "/" ? "/ui.js" : req.url || "/ui.js";
+        const filePath = join(ctx.getPluginDir(), "dist", url);
+        const ext = extname(filePath).toLowerCase();
+        res.setHeader("Content-Type", CONTENT_TYPES[ext] || "application/octet-stream");
+        res.setHeader("Access-Control-Allow-Origin", "*");
+        try {
+            const stream = createReadStream(filePath);
+            stream.pipe(res);
+            stream.on("error", () => {
+                res.statusCode = 404;
+                res.end("Not found");
+            });
+        }
+        catch {
+            res.statusCode = 500;
+            res.end("Error");
+        }
+    });
+    server.listen(port, "127.0.0.1", () => {
+        ctx?.log.info(`Router UI available at http://127.0.0.1:${port}`);
+    });
+    return server;
+}
+function matchesRoute(route, input) {
+    if (route.sourceSession && route.sourceSession !== input.session)
+        return false;
+    if (route.channelType && route.channelType !== input.channel?.type)
+        return false;
+    if (route.channelId && route.channelId !== input.channel?.id)
+        return false;
+    return true;
+}
+async function fanOutToSessions(route, input) {
+    const targets = route.targetSessions || [];
+    for (const target of targets) {
+        if (!target || target === input.session)
+            continue;
+        await ctx.inject(target, input.message);
+    }
+}
+async function fanOutToChannels(route, output) {
+    const channels = ctx.getChannelsForSession(output.session);
+    for (const adapter of channels) {
+        if (route.channelType && adapter.channel.type !== route.channelType)
+            continue;
+        if (route.channelId && adapter.channel.id !== route.channelId)
+            continue;
+        await adapter.send(output.response);
+    }
+}
+export default {
+    name: "router",
+    version: "0.2.0",
+    description: "Message routing middleware between channels and sessions",
+    async init(pluginContext) {
+        ctx = pluginContext;
+        const config = ctx.getConfig();
+        const uiPort = config.uiPort || 7333;
+        uiServer = startUIServer(uiPort);
+        if (ctx.registerUiComponent) {
+            ctx.registerUiComponent({
+                id: "router-panel",
+                title: "Message Router",
+                moduleUrl: `http://127.0.0.1:${uiPort}/ui.js`,
+                slot: "settings",
+                description: "Configure message routing between sessions",
+            });
+            ctx.log.info("Registered Router UI component in WOPR settings");
+        }
+        ctx.registerMiddleware({
+            name: "router",
+            async onIncoming(input) {
+                const config = ctx.getConfig();
+                const routes = config.routes || [];
+                for (const route of routes) {
+                    if (!matchesRoute(route, input))
+                        continue;
+                    await fanOutToSessions(route, input);
+                }
+                return input.message;
+            },
+            async onOutgoing(output) {
+                const config = ctx.getConfig();
+                const routes = config.outgoingRoutes || [];
+                for (const route of routes) {
+                    if (route.sourceSession && route.sourceSession !== output.session)
+                        continue;
+                    await fanOutToChannels(route, output);
+                }
+                return output.response;
+            },
+        });
+    },
+    async shutdown() {
+        if (uiServer) {
+            ctx?.log.info("Router UI server shutting down...");
+            await new Promise((resolve) => uiServer.close(() => resolve()));
+            uiServer = null;
+        }
+    },
+};

package/dist/ui.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Router Plugin UI Component for WOPR
+ *
+ * SolidJS component for managing message routing rules.
+ */
+interface Route {
+    sourceSession: string;
+    targetSessions: string[];
+    channelType?: string;
+}
+interface RouterConfig {
+    routes?: Route[];
+    outgoingRoutes?: Route[];
+}
+interface PluginConfig {
+    plugins?: {
+        data?: {
+            router?: RouterConfig;
+        };
+    };
+}
+interface RouterPluginProps {
+    api: {
+        getConfig(): Promise<PluginConfig>;
+    };
+    saveConfig(config: RouterConfig): Promise<void>;
+}
+export default function RouterPluginUI(props: RouterPluginProps): HTMLDivElement;
+export {};

package/dist/ui.js

@@ -0,0 +1,121 @@
+// src/ui.ts
+var { createSignal, onMount } = window.Solid || Solid;
+function RouterPluginUI(props) {
+  const [routes, setRoutes] = createSignal([]);
+  const [outgoingRoutes, setOutgoingRoutes] = createSignal([]);
+  const [newSource, setNewSource] = createSignal("");
+  const [newTargets, setNewTargets] = createSignal("");
+  const [newChannelType, setNewChannelType] = createSignal("");
+  onMount(async () => {
+    const config = await props.api.getConfig();
+    const routerConfig = config.plugins?.data?.router || {};
+    setRoutes(routerConfig.routes || []);
+    setOutgoingRoutes(routerConfig.outgoingRoutes || []);
+  });
+  const handleAddRoute = async () => {
+    if (!newSource() || !newTargets())
+      return;
+    const newRoute = {
+      sourceSession: newSource(),
+      targetSessions: newTargets().split(",").map((s) => s.trim()).filter(Boolean),
+      channelType: newChannelType() || void 0
+    };
+    const updatedRoutes = [...routes(), newRoute];
+    await props.saveConfig({
+      routes: updatedRoutes,
+      outgoingRoutes: outgoingRoutes()
+    });
+    setRoutes(updatedRoutes);
+    setNewSource("");
+    setNewTargets("");
+    setNewChannelType("");
+  };
+  const handleDeleteRoute = async (index) => {
+    const updatedRoutes = routes().filter((_, i) => i !== index);
+    await props.saveConfig({
+      routes: updatedRoutes,
+      outgoingRoutes: outgoingRoutes()
+    });
+    setRoutes(updatedRoutes);
+  };
+  const container = document.createElement("div");
+  container.className = "router-plugin-ui";
+  const header = document.createElement("div");
+  header.className = "flex items-center justify-between mb-4";
+  header.innerHTML = `
+    <h3 class="text-lg font-semibold">Message Router</h3>
+    <span class="px-2 py-1 rounded text-xs bg-blue-500/20 text-blue-400">
+      ${routes().length} rules
+    </span>
+  `;
+  container.appendChild(header);
+  const routesSection = document.createElement("div");
+  routesSection.className = "mb-4";
+  const updateRoutesList = () => {
+    routesSection.innerHTML = "";
+    if (routes().length === 0) {
+      routesSection.innerHTML = `
+        <div class="text-sm text-wopr-muted p-3 bg-wopr-panel rounded border border-wopr-border">
+          No routing rules configured. Messages will not be forwarded.
+        </div>
+      `;
+    } else {
+      routes().forEach((route, index) => {
+        const item = document.createElement("div");
+        item.className = "p-3 bg-wopr-panel rounded border border-wopr-border flex items-center justify-between mb-2";
+        item.innerHTML = `
+          <div>
+            <div class="font-medium">${route.sourceSession} \u2192 ${route.targetSessions.join(", ")}</div>
+            ${route.channelType ? `<div class="text-sm text-wopr-muted">Channel: ${route.channelType}</div>` : ""}
+          </div>
+          <button class="delete-route px-3 py-1 bg-red-500/20 text-red-400 rounded text-sm hover:bg-red-500/30">
+            Delete
+          </button>
+        `;
+        const deleteBtn = item.querySelector(".delete-route");
+        if (deleteBtn) {
+          deleteBtn.addEventListener("click", () => handleDeleteRoute(index));
+        }
+        routesSection.appendChild(item);
+      });
+    }
+  };
+  routes(updateRoutesList);
+  updateRoutesList();
+  container.appendChild(routesSection);
+  const formSection = document.createElement("div");
+  formSection.className = "p-3 bg-wopr-panel rounded border border-wopr-border";
+  formSection.innerHTML = `
+    <h4 class="text-sm font-semibold text-wopr-muted uppercase mb-3">Add Route</h4>
+    <div class="space-y-2">
+      <input type="text" placeholder="Source session" class="source-input w-full bg-wopr-bg border border-wopr-border rounded px-3 py-2 text-sm" />
+      <input type="text" placeholder="Target sessions (comma-separated)" class="targets-input w-full bg-wopr-bg border border-wopr-border rounded px-3 py-2 text-sm" />
+      <input type="text" placeholder="Channel type (optional)" class="channel-input w-full bg-wopr-bg border border-wopr-border rounded px-3 py-2 text-sm" />
+      <button class="add-btn w-full px-4 py-2 bg-wopr-accent text-wopr-bg rounded text-sm font-medium hover:bg-wopr-accent/90">
+        Add Route
+      </button>
+    </div>
+  `;
+  const sourceInput = formSection.querySelector(".source-input");
+  const targetsInput = formSection.querySelector(".targets-input");
+  const channelInput = formSection.querySelector(".channel-input");
+  sourceInput.addEventListener("input", (e) => setNewSource(e.target.value));
+  targetsInput.addEventListener("input", (e) => setNewTargets(e.target.value));
+  channelInput.addEventListener("input", (e) => setNewChannelType(e.target.value));
+  const addBtn = formSection.querySelector(".add-btn");
+  if (addBtn) {
+    addBtn.addEventListener("click", handleAddRoute);
+  }
+  container.appendChild(formSection);
+  const infoSection = document.createElement("div");
+  infoSection.className = "mt-4 p-3 bg-wopr-panel/50 rounded border border-wopr-border text-sm text-wopr-muted";
+  infoSection.innerHTML = `
+    <p class="mb-1"><strong>Incoming:</strong> Messages to source session are forwarded to targets.</p>
+    <p><strong>Outgoing:</strong> Responses are sent back to originating channel.</p>
+  `;
+  container.appendChild(infoSection);
+  return container;
+}
+export {
+  RouterPluginUI as default
+};

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "wopr-plugin-router",
+  "version": "0.3.0",
+  "description": "Message routing middleware for WOPR",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "scripts": {
+    "build": "tsc && npm run build:ui",
+    "build:ui": "esbuild src/ui.ts --bundle --format=esm --outfile=dist/ui.js --target=es2020",
+    "dev": "tsc --watch",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "npm run build"
+  },
+  "wopr": {
+    "type": "plugin",
+    "minVersion": "1.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "esbuild": "^0.20.0",
+    "typescript": "^5.3.0"
+  },
+  "files": [
+    "dist"
+  ]
+}