move rhailib to herolib

rhailib/research/repl/README.md

@@ -0,0 +1,77 @@
+# Rhai REPL CLI for Circle WebSocket Servers
+
+This crate provides a command-line interface (CLI) to interact with Rhai scripts executed on remote Circle WebSocket servers. It includes both an interactive REPL and a non-interactive example.
+
+## Prerequisites
+
+1.  **Circle Orchestrator Running**: Ensure the `circles_orchestrator` is running. This application manages and starts the individual Circle WebSocket servers.
+    To run the orchestrator:
+    ```bash
+    cd /path/to/herocode/circles/cmd
+    cargo run
+    ```
+    By default, this will start servers based on the `circles.json` configuration (e.g., "Alpha Circle" on `ws://127.0.0.1:8081/ws`).
+
+2.  **Redis Server**: Ensure a Redis server is running and accessible at `redis://127.0.0.1:6379` (this is the default used by the orchestrator and its components).
+
+## Usage
+
+Navigate to this crate's directory:
+```bash
+cd /path/to/herocode/circles/ui_repl
+```
+
+### 1. Interactive REPL
+
+The main binary of this crate is an interactive REPL.
+
+**To run with default WebSocket URL (`ws://127.0.0.1:8081/ws`):**
+```bash
+cargo run
+```
+
+**To specify a WebSocket URL:**
+```bash
+cargo run ws://<your-circle-server-ip>:<port>/ws
+# Example for "Beta Circle" if configured on port 8082:
+# cargo run ws://127.0.0.1:8082/ws
+```
+
+Once connected, you can:
+- Type single-line Rhai scripts directly and press Enter.
+- Use Vi keybindings for editing the current input line (thanks to `rustyline`).
+- Type `.edit` to open your `$EDITOR` (or `vi` by default) for multi-line script input. Save and close the editor to execute the script.
+- Type `.run <filepath>` (or `run <filepath>`) to execute a Rhai script from a local file.
+- Type `exit` or `quit` to close the REPL.
+
+Command history is saved to `.rhai_repl_history.txt` in the directory where you run the REPL.
+
+### 2. Non-Interactive Example (`connect_and_play`)
+
+This example connects to a WebSocket server, sends a predefined Rhai script, prints the response, and then disconnects.
+
+**To run with default WebSocket URL (`ws://127.0.0.1:8081/ws`):**
+```bash
+cargo run --example connect_and_play
+```
+
+**To specify a WebSocket URL for the example:**
+```bash
+cargo run --example connect_and_play ws://<your-circle-server-ip>:<port>/ws
+# Example:
+# cargo run --example connect_and_play ws://127.0.0.1:8082/ws
+```
+
+The example script is:
+```rhai
+let a = 10;
+let b = 32;
+let message = "Hello from example script!";
+message + " Result: " + (a + b)
+```
+
+## Logging
+
+Both the REPL and the example use the `tracing` crate for logging. You can control log levels using the `RUST_LOG` environment variable. For example, to see debug logs from the `circle_client_ws` library:
+```bash
+RUST_LOG=info,circle_client_ws=debug cargo run --example connect_and_play