feat: M1.4.3 - Beatrice REPL Implementation (Interactive Shell) (#228)

* feat: add REPL module structure with special commands (Task 1)

* feat: implement REPL main loop with special command handling (Task 2)

* test: add REPL integration tests for all features (Task 3)

* docs: add comprehensive REPL implementation documentation (Task 4)

Author: LyeZinho

crates/mimi-cli/src/repl/completion.rs

@@ -0,0 +1,20 @@
+//! Command completion for REPL (stub for future enhancement)
+
+#[derive(Debug, Clone)]
+pub struct CompletionProvider;
+
+impl CompletionProvider {
+    pub fn new() -> Self {
+        Self
+    }
+
+    pub fn complete(&self, _partial: &str) -> Vec<String> {
+        vec![]
+    }
+}
+
+impl Default for CompletionProvider {
+    fn default() -> Self {
+        Self::new()
+    }
+}

crates/mimi-cli/src/repl/editor.rs

@@ -0,0 +1,32 @@
+//! Editor for REPL (Phase 1: minimal, Phase 2: rustyline)
+
+#[derive(Debug, Clone)]
+pub struct ReplEditor {
+    history: Vec<String>,
+    max_history: usize,
+}
+
+impl ReplEditor {
+    pub fn new(max_history: usize) -> Self {
+        Self {
+            history: Vec::new(),
+            max_history,
+        }
+    }
+
+    pub fn add_to_history(&mut self, line: &str) {
+        self.history.push(line.to_string());
+        if self.history.len() > self.max_history {
+            self.history.remove(0);
+        }
+    }
+
+    pub fn get_history(&self, count: usize) -> Vec<String> {
+        let start = if self.history.len() > count {
+            self.history.len() - count
+        } else {
+            0
+        };
+        self.history[start..].to_vec()
+    }
+}

crates/mimi-cli/src/repl/loop.rs

@@ -0,0 +1,137 @@
+//! Main REPL event loop
+
+use std::io::{self, BufRead, Write};
+
+use super::{PromptState, ReplConfig, ReplEditor, SpecialCommand};
+
+pub async fn run_repl(config: ReplConfig) -> io::Result<()> {
+    let mut editor = ReplEditor::new(config.max_history);
+    let stdin = io::stdin();
+    let reader = stdin.lock();
+    let mut lines = reader.lines();
+
+    let mut prompt_state = PromptState::Default;
+    let mut multiline_buffer = String::new();
+
+    run_startup_script(&config, &mut editor).await;
+
+    print_prompt(prompt_state);
+
+    while let Some(Ok(line)) = lines.next() {
+        let line = line.trim();
+
+        if line.is_empty() {
+            print_prompt(prompt_state);
+            continue;
+        }
+
+        if line.ends_with('\\') {
+            multiline_buffer.push_str(&line[..line.len() - 1]);
+            multiline_buffer.push(' ');
+            prompt_state = PromptState::Continuation;
+            print_prompt(prompt_state);
+            continue;
+        }
+
+        if !multiline_buffer.is_empty() {
+            multiline_buffer.push_str(line);
+        } else {
+            multiline_buffer = line.to_string();
+        }
+
+        editor.add_to_history(&multiline_buffer);
+
+        match execute_line(&multiline_buffer, &mut editor) {
+            LineExecution::Exit => break,
+            LineExecution::Continue => {},
+        }
+
+        multiline_buffer.clear();
+        prompt_state = PromptState::Default;
+        print_prompt(prompt_state);
+    }
+
+    println!();
+    Ok(())
+}
+
+enum LineExecution {
+    Exit,
+    Continue,
+}
+
+fn execute_line(line: &str, editor: &mut ReplEditor) -> LineExecution {
+    if let Some(cmd) = SpecialCommand::parse(line) {
+        let output = cmd.execute();
+
+        if cmd == SpecialCommand::Exit {
+            return LineExecution::Exit;
+        }
+
+        if cmd == SpecialCommand::Clear {
+            print!("{}", output);
+            let _ = io::stdout().flush();
+        } else if matches!(cmd, SpecialCommand::History(_)) {
+            let history_lines = editor.get_history(20);
+            for (i, h_line) in history_lines.iter().enumerate() {
+                println!("  {}: {}", i + 1, h_line);
+            }
+        } else {
+            println!("{}", output);
+        }
+    } else {
+        println!(
+            "REPL: parsed command '{}' (execution deferred to M1.4.6)",
+            line
+        );
+    }
+
+    LineExecution::Continue
+}
+
+fn print_prompt(state: PromptState) {
+    print!("{}", state.prompt_string());
+    let _ = io::stdout().flush();
+}
+
+async fn run_startup_script(config: &ReplConfig, editor: &mut ReplEditor) {
+    if let Some(script_path) = &config.startup_script {
+        if let Ok(content) = std::fs::read_to_string(script_path) {
+            for script_line in content.lines() {
+                let trimmed = script_line.trim();
+                if !trimmed.is_empty() && !trimmed.starts_with('#') {
+                    println!("{}{}", PromptState::Default.prompt_string(), trimmed);
+                    editor.add_to_history(trimmed);
+                    match execute_line(trimmed, editor) {
+                        LineExecution::Exit => break,
+                        LineExecution::Continue => {},
+                    }
+                }
+            }
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_line_execution_exit() {
+        let mut editor = ReplEditor::new(1000);
+        let result = execute_line(".exit", &mut editor);
+        assert!(matches!(result, LineExecution::Exit));
+    }
+
+    #[test]
+    fn test_line_execution_regular() {
+        let mut editor = ReplEditor::new(1000);
+        let result = execute_line("some command", &mut editor);
+        assert!(matches!(result, LineExecution::Continue));
+    }
+
+    #[test]
+    fn test_print_prompt_default() {
+        print_prompt(PromptState::Default);
+    }
+}

crates/mimi-cli/src/repl/mod.rs

@@ -0,0 +1,77 @@
+//! Interactive REPL for continuous user interaction
+
+pub mod completion;
+pub mod editor;
+pub mod r#loop;
+pub mod special_commands;
+
+pub use editor::ReplEditor;
+pub use r#loop::run_repl;
+pub use special_commands::SpecialCommand;
+
+#[derive(Debug, Clone)]
+pub struct ReplConfig {
+    pub history_file: String,
+    pub max_history: usize,
+    pub no_history: bool,
+    pub startup_script: Option<String>,
+    pub completion: bool,
+}
+
+impl Default for ReplConfig {
+    fn default() -> Self {
+        Self {
+            history_file: format!(
+                "{}/.mimi/repl_history",
+                std::env::var("HOME").unwrap_or_else(|_| ".".to_string())
+            ),
+            max_history: 1000,
+            no_history: false,
+            startup_script: None,
+            completion: true,
+        }
+    }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum PromptState {
+    Default,
+    Following(u32),
+    Debug,
+    Continuation,
+}
+
+impl PromptState {
+    pub fn prompt_string(&self) -> String {
+        match self {
+            Self::Default => "mimi> ".to_string(),
+            Self::Following(task_id) => format!("mimi [task-{}]> ", task_id),
+            Self::Debug => "mimi [debug]> ".to_string(),
+            Self::Continuation => "... ".to_string(),
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_default_config() {
+        let config = ReplConfig::default();
+        assert_eq!(config.max_history, 1000);
+        assert!(!config.no_history);
+        assert!(config.completion);
+    }
+
+    #[test]
+    fn test_prompt_strings() {
+        assert_eq!(PromptState::Default.prompt_string(), "mimi> ");
+        assert_eq!(
+            PromptState::Following(123).prompt_string(),
+            "mimi [task-123]> "
+        );
+        assert_eq!(PromptState::Debug.prompt_string(), "mimi [debug]> ");
+        assert_eq!(PromptState::Continuation.prompt_string(), "... ");
+    }
+}