Replace serial compiler helper with stateful REPL

Author: fffonion

Cargo.lock

@@ -16,22 +16,23 @@ path = "src/bin/rustscript-compile-vmbc.rs"
 required-features = ["host"]
 
 [[bin]]
-name = "rustscript-repl-compile"
-path = "src/bin/rustscript-repl-compile.rs"
+name = "rustscript-serial-repl"
+path = "src/bin/rustscript-serial-repl.rs"
 required-features = ["host"]
 
 [features]
 default = ["host"]
-host = ["dep:vm", "vm/runtime"]
+host = ["dep:serialport", "dep:vm", "vm/runtime"]
 esp32c3 = ["dep:pd_vm_nostd"]
 esp32s31 = ["dep:pd_vm_nostd"]
 arduino = ["dep:pd_vm_nostd"]
 wifi = []
 bluetooth = []
 
 [dependencies]
-pd_vm_nostd = { package = "pd-vm-nostd", git = "https://github.com/rustscript-lang/rustscript.git", rev = "ab04637a9b6192dd4f37b7e6abe4dde83f2fc710", version = "0.1.0", optional = true }
-vm = { package = "pd-vm", git = "https://github.com/rustscript-lang/rustscript.git", rev = "ab04637a9b6192dd4f37b7e6abe4dde83f2fc710", version = "0.1.0", default-features = false, optional = true }
+pd_vm_nostd = { package = "pd-vm-nostd", git = "https://github.com/rustscript-lang/rustscript.git", rev = "5380c19", version = "0.1.0", optional = true }
+serialport = { version = "4.8.1", default-features = false, optional = true }
+vm = { package = "pd-vm", git = "https://github.com/rustscript-lang/rustscript.git", rev = "5380c19", version = "0.1.0", default-features = false, optional = true }
 
 [profile.release]
 opt-level = "z"

Cargo.toml

@@ -120,21 +120,41 @@ RSS input compilation uses `rustscript-compile-vmbc` from `PATH`, or the compile
 checkout through Cargo. A raw `.vmbc` file can be copied directly to the SD path; SD files do not
 use the flash-partition header.
 
-## Serial VMBC REPL
+## Serial REPL
 
-When neither startup source exists, the firmware presents a VMBC-oriented serial REPL. Commands are
-`load`, `install`, `run`, `info`, and `help`. `load` executes a transferred VMBC payload without
-writing flash; `install` writes the script partition first. The helper implements the binary framing:
+When neither startup source exists, the firmware accepts both the legacy VMBC commands and an
+interactive source REPL. Build and start the source REPL on the development machine:
+
+```bash
+cargo build --release --bin rustscript-serial-repl
+./target/release/rustscript-serial-repl /dev/ttyACM0 115200
+```
+
+The prompt follows `pd-vm-run`: enter one expression or statement at a time and expression results
+are printed immediately. Bindings, mutations, type metadata, and moved-value state carry across
+entries. Delimiter-based multiline input uses the `...>` prompt; `.cancel` clears pending input,
+`.clear` clears session locals, and `.quit` exits.
+
+```text
+rss> let mut x = 40;
+rss> x = x + 2;
+rss> x
+=> 42
+```
+
+Source compilation stays on the development machine. Each entry is sent as VMBC plus its current
+local values using fixed-length binary frames; the firmware contains only the decoder and
+interpreter.
+
+The existing `load`, `install`, `run`, `info`, and `help` commands remain available. To send a
+precompiled payload directly:
 
 ```bash
 python -m pip install pyserial
 python scripts/repl_vmbc.py app.vmbc --port /dev/ttyACM0
 python scripts/repl_vmbc.py app.vmbc --port /dev/ttyACM0 --install
 ```
 
-Source compilation stays on the development machine; the firmware image contains the decoder and
-interpreter, without the desktop compiler.
-
 ## Build
 
 The repository root is a complete PlatformIO project:

README.md

@@ -278,19 +278,31 @@ void rustscript_repl_source() {
             delay(10);
             continue;
         }
-        String header = Serial.readStringUntil('\n');
-        header.trim();
-        if (header.length() == 0) {
-            continue;
-        }
-        // Binary protocol
-        if (header.startsWith(REPL_MAGIC) && header.length() == strlen(REPL_MAGIC) + 8) {
-            const uint32_t program_len = *reinterpret_cast<const uint32_t *>(header.c_str() + 4);
-            const uint32_t state_len = *reinterpret_cast<const uint32_t *>(header.c_str() + 8);
+        if (Serial.peek() == 'R') {
+            uint8_t frame_header[REPL_FRAME_HEADER_SIZE] = {};
+            if (!read_serial_payload(frame_header, sizeof(frame_header))) {
+                continue;
+            }
+            if (std::memcmp(frame_header, REPL_REQUEST_MAGIC, 4) != 0) {
+                Serial.println("rss:error=invalid-repl-magic");
+                continue;
+            }
+            uint32_t program_len = 0;
+            uint32_t state_len = 0;
+            std::memcpy(&program_len, frame_header + 4, sizeof(program_len));
+            std::memcpy(&state_len, frame_header + 8, sizeof(state_len));
+            if (program_len == 0 || state_len == 0 ||
+                program_len > REPL_MAX_FRAME_SIZE || state_len > REPL_MAX_FRAME_SIZE ||
+                program_len > REPL_MAX_FRAME_SIZE - state_len) {
+                Serial.println("rss:error=invalid-repl-length");
+                continue;
+            }
             uint8_t *program = read_serial_binary(program_len);
-            if (program == nullptr) continue;
-            uint8_t *state = state_len > 0 ? read_serial_binary(state_len) : nullptr;
-            if (state_len > 0 && state == nullptr) {
+            if (program == nullptr) {
+                continue;
+            }
+            uint8_t *state = read_serial_binary(state_len);
+            if (state == nullptr) {
                 std::free(program);
                 continue;
             }
@@ -303,14 +315,24 @@ void rustscript_repl_source() {
             );
             std::free(program);
             std::free(state);
+
+            uint8_t response_header[REPL_FRAME_HEADER_SIZE] = {};
+            std::memcpy(response_header, REPL_RESPONSE_MAGIC, 4);
+            const uint32_t output_len = static_cast<uint32_t>(output.len);
+            std::memcpy(response_header + 4, &status, sizeof(status));
+            std::memcpy(response_header + 8, &output_len, sizeof(output_len));
+            Serial.write(response_header, sizeof(response_header));
             if (output.len > 0) {
-                Serial.printf("rss:%c%04x", 'D', static_cast<unsigned>(output.len));
                 Serial.write(output.data, output.len);
                 rustscript_buffer_free(output);
-            } else {
-                Serial.printf("rss:repl-status=%d\n", static_cast<int>(status));
             }
-            Serial.print("rss:pd-vm> ");
+            Serial.flush();
+            continue;
+        }
+
+        String header = Serial.readStringUntil('\n');
+        header.trim();
+        if (header.length() == 0) {
             continue;
         }
         // Legacy commands

firmware/script_loader.cpp

@@ -16,6 +16,7 @@ enum rustscript_status {
     RUSTSCRIPT_STATUS_HOST_ERROR = -3,
     RUSTSCRIPT_STATUS_OUT_OF_FUEL = -4,
     RUSTSCRIPT_STATUS_VM_ERROR = -5,
+    RUSTSCRIPT_STATUS_INVALID_REPL_STATE = -6,
 };
 
 enum rustscript_value_tag {

include/rustscript_embedded.h

@@ -22,15 +22,10 @@ void rustscript_repl();
 }
 #endif
 
-#define REPL_MAGIC "RSSR"
-#define REPL_LEN_SIZE 4
-#define REPL_CMD_HELLO  1
-#define REPL_CMD_HELLO_RESPONSE 2
-#define REPL_CMD_PAYLOAD 3
-#define REPL_CMD_PAYLOAD_RESPONSE 4
-#define REPL_CMD_ERROR  5
+#define REPL_REQUEST_MAGIC "RSSQ"
+#define REPL_RESPONSE_MAGIC "RSSP"
+#define REPL_FRAME_HEADER_SIZE 12
+#define REPL_MAX_FRAME_SIZE (16U * 1024U * 1024U)
 
-// Power-on state: send HELLO -> receive HELLO_RESPONSE (or timeout -> legacy PROMPT).
-// Main loop: send PAYLOAD (program_len + state_len + program + state)
-//        -> receive PAYLOAD_RESPONSE (status_code + response_len + response)
-//        or ERROR (message_len + message).
+// Request:  "RSSQ" + program_len(u32 LE) + state_len(u32 LE) + program + state.
+// Response: "RSSP" + status(i32 LE) + response_len(u32 LE) + response.