command-stream 0.9.1 → 0.9.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "command-stream",
-  "version": "0.9.1",
+  "version": "0.9.2",
   "description": "Modern $ shell utility library with streaming, async iteration, and EventEmitter support, optimized for Bun runtime",
   "type": "module",
   "main": "js/src/$.mjs",

package/rust/src/ansi.rs

@@ -0,0 +1,194 @@
+//! ANSI control character utilities for command-stream
+//!
+//! This module handles stripping and processing of ANSI escape codes
+//! and control characters from text output.
+
+/// ANSI control character utilities
+pub struct AnsiUtils;
+
+impl AnsiUtils {
+    /// Strip ANSI escape sequences from text
+    ///
+    /// Removes color codes, cursor movement, and other ANSI escape sequences
+    /// while preserving the actual text content.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use command_stream::ansi::AnsiUtils;
+    ///
+    /// let text = "\x1b[31mRed text\x1b[0m";
+    /// assert_eq!(AnsiUtils::strip_ansi(text), "Red text");
+    /// ```
+    pub fn strip_ansi(text: &str) -> String {
+        let re = regex::Regex::new(r"\x1b\[[0-9;]*[mGKHFJ]").unwrap();
+        re.replace_all(text, "").to_string()
+    }
+
+    /// Strip control characters from text, preserving newlines, carriage returns, and tabs
+    ///
+    /// Removes control characters (ASCII 0x00-0x1F and 0x7F) except:
+    /// - Newlines (\n = 0x0A)
+    /// - Carriage returns (\r = 0x0D)
+    /// - Tabs (\t = 0x09)
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use command_stream::ansi::AnsiUtils;
+    ///
+    /// let text = "Hello\x00World\nNew line\tTab";
+    /// assert_eq!(AnsiUtils::strip_control_chars(text), "HelloWorld\nNew line\tTab");
+    /// ```
+    pub fn strip_control_chars(text: &str) -> String {
+        text.chars()
+            .filter(|c| {
+                // Preserve newlines (\n = \x0A), carriage returns (\r = \x0D), and tabs (\t = \x09)
+                !matches!(*c as u32,
+                    0x00..=0x08 | 0x0B | 0x0C | 0x0E..=0x1F | 0x7F
+                )
+            })
+            .collect()
+    }
+
+    /// Strip both ANSI sequences and control characters
+    ///
+    /// Combines `strip_ansi` and `strip_control_chars` for complete text cleaning.
+    pub fn strip_all(text: &str) -> String {
+        Self::strip_control_chars(&Self::strip_ansi(text))
+    }
+
+    /// Clean data for processing (strips ANSI and control chars)
+    ///
+    /// Alias for `strip_all` - provides semantic clarity when processing
+    /// data that needs to be cleaned for further processing.
+    pub fn clean_for_processing(data: &str) -> String {
+        Self::strip_all(data)
+    }
+}
+
+/// Configuration for ANSI handling
+///
+/// Controls how ANSI escape codes and control characters are processed
+/// in command output.
+#[derive(Debug, Clone)]
+pub struct AnsiConfig {
+    /// Whether to preserve ANSI escape sequences in output
+    pub preserve_ansi: bool,
+    /// Whether to preserve control characters in output
+    pub preserve_control_chars: bool,
+}
+
+impl Default for AnsiConfig {
+    fn default() -> Self {
+        AnsiConfig {
+            preserve_ansi: true,
+            preserve_control_chars: true,
+        }
+    }
+}
+
+impl AnsiConfig {
+    /// Create a new AnsiConfig that preserves everything (default)
+    pub fn new() -> Self {
+        Self::default()
+    }
+
+    /// Create a config that strips all ANSI and control characters
+    pub fn strip_all() -> Self {
+        AnsiConfig {
+            preserve_ansi: false,
+            preserve_control_chars: false,
+        }
+    }
+
+    /// Process output according to config settings
+    ///
+    /// Applies the configured stripping rules to the input data.
+    pub fn process_output(&self, data: &str) -> String {
+        if !self.preserve_ansi && !self.preserve_control_chars {
+            AnsiUtils::clean_for_processing(data)
+        } else if !self.preserve_ansi {
+            AnsiUtils::strip_ansi(data)
+        } else if !self.preserve_control_chars {
+            AnsiUtils::strip_control_chars(data)
+        } else {
+            data.to_string()
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_strip_ansi() {
+        let text = "\x1b[31mRed text\x1b[0m";
+        assert_eq!(AnsiUtils::strip_ansi(text), "Red text");
+    }
+
+    #[test]
+    fn test_strip_ansi_multiple_codes() {
+        let text = "\x1b[1m\x1b[32mBold Green\x1b[0m Normal";
+        assert_eq!(AnsiUtils::strip_ansi(text), "Bold Green Normal");
+    }
+
+    #[test]
+    fn test_strip_control_chars() {
+        let text = "Hello\x00World\nNew line\tTab";
+        assert_eq!(
+            AnsiUtils::strip_control_chars(text),
+            "HelloWorld\nNew line\tTab"
+        );
+    }
+
+    #[test]
+    fn test_strip_control_chars_preserves_whitespace() {
+        let text = "Line1\nLine2\r\nLine3\tTabbed";
+        assert_eq!(
+            AnsiUtils::strip_control_chars(text),
+            "Line1\nLine2\r\nLine3\tTabbed"
+        );
+    }
+
+    #[test]
+    fn test_strip_all() {
+        let text = "\x1b[31mRed\x00text\x1b[0m";
+        assert_eq!(AnsiUtils::strip_all(text), "Redtext");
+    }
+
+    #[test]
+    fn test_ansi_config_default() {
+        let config = AnsiConfig::default();
+        let text = "\x1b[31mRed\x00text\x1b[0m";
+        assert_eq!(config.process_output(text), text);
+    }
+
+    #[test]
+    fn test_ansi_config_strip_all() {
+        let config = AnsiConfig::strip_all();
+        let text = "\x1b[31mRed\x00text\x1b[0m";
+        assert_eq!(config.process_output(text), "Redtext");
+    }
+
+    #[test]
+    fn test_ansi_config_strip_ansi_only() {
+        let config = AnsiConfig {
+            preserve_ansi: false,
+            preserve_control_chars: true,
+        };
+        let text = "\x1b[31mRed text\x1b[0m";
+        assert_eq!(config.process_output(text), "Red text");
+    }
+
+    #[test]
+    fn test_ansi_config_strip_control_only() {
+        let config = AnsiConfig {
+            preserve_ansi: true,
+            preserve_control_chars: false,
+        };
+        let text = "Hello\x00World";
+        assert_eq!(config.process_output(text), "HelloWorld");
+    }
+}

package/rust/src/events.rs

@@ -0,0 +1,305 @@
+//! Event emitter for stream events
+//!
+//! This module provides an EventEmitter-like implementation for ProcessRunner
+//! events, similar to the JavaScript StreamEmitter class.
+
+use std::collections::HashMap;
+use std::sync::Arc;
+use tokio::sync::RwLock;
+
+use crate::trace::trace_lazy;
+
+/// Event types that can be emitted by ProcessRunner
+#[derive(Debug, Clone, Hash, Eq, PartialEq)]
+pub enum EventType {
+    /// Stdout data received
+    Stdout,
+    /// Stderr data received
+    Stderr,
+    /// Combined data event (contains type and data)
+    Data,
+    /// Process ended
+    End,
+    /// Process exited with code
+    Exit,
+    /// Error occurred
+    Error,
+    /// Process spawned
+    Spawn,
+}
+
+impl std::fmt::Display for EventType {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            EventType::Stdout => write!(f, "stdout"),
+            EventType::Stderr => write!(f, "stderr"),
+            EventType::Data => write!(f, "data"),
+            EventType::End => write!(f, "end"),
+            EventType::Exit => write!(f, "exit"),
+            EventType::Error => write!(f, "error"),
+            EventType::Spawn => write!(f, "spawn"),
+        }
+    }
+}
+
+/// Event data variants
+#[derive(Debug, Clone)]
+pub enum EventData {
+    /// String data (for stdout, stderr)
+    String(String),
+    /// Exit code
+    ExitCode(i32),
+    /// Data event with type and content
+    TypedData { data_type: String, data: String },
+    /// Command result
+    Result(crate::CommandResult),
+    /// Error message
+    Error(String),
+    /// No data
+    None,
+}
+
+/// Type alias for event listeners
+type Listener = Arc<dyn Fn(EventData) + Send + Sync>;
+
+/// Event emitter for ProcessRunner events
+///
+/// Provides on(), once(), off(), and emit() methods similar to Node.js EventEmitter.
+pub struct StreamEmitter {
+    listeners: RwLock<HashMap<EventType, Vec<Listener>>>,
+}
+
+impl Default for StreamEmitter {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+impl StreamEmitter {
+    /// Create a new event emitter
+    pub fn new() -> Self {
+        StreamEmitter {
+            listeners: RwLock::new(HashMap::new()),
+        }
+    }
+
+    /// Register a listener for an event
+    ///
+    /// # Arguments
+    /// * `event` - The event type to listen for
+    /// * `listener` - The callback function to invoke
+    ///
+    /// # Example
+    /// ```ignore
+    /// emitter.on(EventType::Stdout, |data| {
+    ///     if let EventData::String(s) = data {
+    ///         println!("Got stdout: {}", s);
+    ///     }
+    /// });
+    /// ```
+    pub async fn on<F>(&self, event: EventType, listener: F)
+    where
+        F: Fn(EventData) + Send + Sync + 'static,
+    {
+        trace_lazy("StreamEmitter", || {
+            format!("on() called for event: {}", event)
+        });
+
+        let mut listeners = self.listeners.write().await;
+        listeners
+            .entry(event)
+            .or_default()
+            .push(Arc::new(listener));
+    }
+
+    /// Register a one-time listener for an event
+    ///
+    /// The listener will be removed after it is invoked once.
+    pub async fn once<F>(&self, event: EventType, listener: F)
+    where
+        F: Fn(EventData) + Send + Sync + 'static,
+    {
+        trace_lazy("StreamEmitter", || {
+            format!("once() called for event: {}", event)
+        });
+
+        // Wrap the listener to track if it's been called
+        let called = Arc::new(std::sync::atomic::AtomicBool::new(false));
+        let called_clone = called.clone();
+
+        let once_listener = move |data: EventData| {
+            if !called_clone.swap(true, std::sync::atomic::Ordering::SeqCst) {
+                listener(data);
+            }
+        };
+
+        self.on(event, once_listener).await;
+    }
+
+    /// Emit an event to all registered listeners
+    ///
+    /// # Arguments
+    /// * `event` - The event type to emit
+    /// * `data` - The event data to pass to listeners
+    pub async fn emit(&self, event: EventType, data: EventData) {
+        let listeners = self.listeners.read().await;
+
+        if let Some(event_listeners) = listeners.get(&event) {
+            trace_lazy("StreamEmitter", || {
+                format!(
+                    "Emitting event {} to {} listeners",
+                    event,
+                    event_listeners.len()
+                )
+            });
+
+            for listener in event_listeners {
+                listener(data.clone());
+            }
+        }
+    }
+
+    /// Remove all listeners for an event
+    ///
+    /// # Arguments
+    /// * `event` - The event type to clear listeners for
+    pub async fn off(&self, event: EventType) {
+        trace_lazy("StreamEmitter", || {
+            format!("off() called for event: {}", event)
+        });
+
+        let mut listeners = self.listeners.write().await;
+        listeners.remove(&event);
+    }
+
+    /// Get the number of listeners for an event
+    pub async fn listener_count(&self, event: &EventType) -> usize {
+        let listeners = self.listeners.read().await;
+        listeners.get(event).map(|v| v.len()).unwrap_or(0)
+    }
+
+    /// Remove all listeners for all events
+    pub async fn remove_all_listeners(&self) {
+        trace_lazy("StreamEmitter", || "Removing all listeners".to_string());
+        let mut listeners = self.listeners.write().await;
+        listeners.clear();
+    }
+}
+
+impl std::fmt::Debug for StreamEmitter {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("StreamEmitter")
+            .field("listeners", &"<RwLock<HashMap<...>>>")
+            .finish()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::sync::atomic::{AtomicUsize, Ordering};
+
+    #[tokio::test]
+    async fn test_emit_basic() {
+        let emitter = StreamEmitter::new();
+        let counter = Arc::new(AtomicUsize::new(0));
+        let counter_clone = counter.clone();
+
+        emitter
+            .on(EventType::Stdout, move |_| {
+                counter_clone.fetch_add(1, Ordering::SeqCst);
+            })
+            .await;
+
+        emitter
+            .emit(EventType::Stdout, EventData::String("test".to_string()))
+            .await;
+
+        assert_eq!(counter.load(Ordering::SeqCst), 1);
+    }
+
+    #[tokio::test]
+    async fn test_once() {
+        let emitter = StreamEmitter::new();
+        let counter = Arc::new(AtomicUsize::new(0));
+        let counter_clone = counter.clone();
+
+        emitter
+            .once(EventType::Exit, move |_| {
+                counter_clone.fetch_add(1, Ordering::SeqCst);
+            })
+            .await;
+
+        // Emit twice
+        emitter.emit(EventType::Exit, EventData::ExitCode(0)).await;
+        emitter.emit(EventType::Exit, EventData::ExitCode(0)).await;
+
+        // Should only be called once
+        assert_eq!(counter.load(Ordering::SeqCst), 1);
+    }
+
+    #[tokio::test]
+    async fn test_off() {
+        let emitter = StreamEmitter::new();
+        let counter = Arc::new(AtomicUsize::new(0));
+        let counter_clone = counter.clone();
+
+        emitter
+            .on(EventType::Stdout, move |_| {
+                counter_clone.fetch_add(1, Ordering::SeqCst);
+            })
+            .await;
+
+        emitter.off(EventType::Stdout).await;
+        emitter
+            .emit(EventType::Stdout, EventData::String("test".to_string()))
+            .await;
+
+        assert_eq!(counter.load(Ordering::SeqCst), 0);
+    }
+
+    #[tokio::test]
+    async fn test_listener_count() {
+        let emitter = StreamEmitter::new();
+
+        assert_eq!(emitter.listener_count(&EventType::Stdout).await, 0);
+
+        emitter.on(EventType::Stdout, |_| {}).await;
+        assert_eq!(emitter.listener_count(&EventType::Stdout).await, 1);
+
+        emitter.on(EventType::Stdout, |_| {}).await;
+        assert_eq!(emitter.listener_count(&EventType::Stdout).await, 2);
+    }
+
+    #[tokio::test]
+    async fn test_multiple_events() {
+        let emitter = StreamEmitter::new();
+        let stdout_counter = Arc::new(AtomicUsize::new(0));
+        let stderr_counter = Arc::new(AtomicUsize::new(0));
+
+        let stdout_clone = stdout_counter.clone();
+        let stderr_clone = stderr_counter.clone();
+
+        emitter
+            .on(EventType::Stdout, move |_| {
+                stdout_clone.fetch_add(1, Ordering::SeqCst);
+            })
+            .await;
+
+        emitter
+            .on(EventType::Stderr, move |_| {
+                stderr_clone.fetch_add(1, Ordering::SeqCst);
+            })
+            .await;
+
+        emitter
+            .emit(EventType::Stdout, EventData::String("out".to_string()))
+            .await;
+        emitter
+            .emit(EventType::Stderr, EventData::String("err".to_string()))
+            .await;
+
+        assert_eq!(stdout_counter.load(Ordering::SeqCst), 1);
+        assert_eq!(stderr_counter.load(Ordering::SeqCst), 1);
+    }
+}

package/rust/src/lib.rs

@@ -9,40 +9,93 @@
 //!
 //! - Async command execution with tokio
 //! - Streaming output via async iterators
+//! - Event-based output handling (on, once, emit)
 //! - Virtual commands for common operations (cat, ls, mkdir, etc.)
 //! - Shell operator support (&&, ||, ;, |)
+//! - Pipeline support with `.pipe()` method and `Pipeline` builder
+//! - Global state management for shell settings
+//! - `cmd!` macro for ergonomic command creation (similar to JS `$` tagged template literals)
 //! - Cross-platform support
 //!
+//! ## Module Organization
+//!
+//! The codebase follows a modular architecture similar to the JavaScript implementation:
+//!
+//! - `ansi` - ANSI escape code handling utilities
+//! - `commands` - Virtual command implementations
+//! - `events` - Event emitter for stream events
+//! - `macros` - The `cmd!` macro for ergonomic command creation
+//! - `pipeline` - Pipeline execution support
+//! - `quote` - Shell quoting utilities
+//! - `shell_parser` - Shell command parsing
+//! - `state` - Global state management
+//! - `stream` - Async streaming and iteration support
+//! - `trace` - Logging and tracing utilities
+//! - `utils` - Command results and virtual command helpers
+//!
 //! ## Quick Start
 //!
 //! ```rust,no_run
-//! use command_stream::run;
+//! use command_stream::{run, cmd};
 //!
 //! #[tokio::main]
 //! async fn main() -> Result<(), Box<dyn std::error::Error>> {
 //!     // Execute a simple command
 //!     let result = run("echo hello world").await?;
 //!     println!("{}", result.stdout);
+//!
+//!     // Using the cmd! macro (similar to JS $ tagged template)
+//!     let name = "world";
+//!     let result = cmd!("echo hello {}", name).await?;
+//!     println!("{}", result.stdout);
+//!
+//!     // Using pipelines
+//!     use command_stream::Pipeline;
+//!     let result = Pipeline::new()
+//!         .add("echo hello world")
+//!         .add("grep world")
+//!         .run()
+//!         .await?;
+//!
 //!     Ok(())
 //! }
 //! ```
 
+// Modular utility modules (following JavaScript modular pattern)
+pub mod ansi;
+pub mod events;
+#[doc(hidden)]
+pub mod macros;
+pub mod pipeline;
+pub mod quote;
+pub mod state;
+pub mod stream;
+pub mod trace;
+
+// Core modules
 pub mod commands;
 pub mod shell_parser;
 pub mod utils;
 
 use std::collections::HashMap;
-use std::env;
 use std::path::PathBuf;
 use std::process::Stdio;
-use std::sync::Arc;
 use tokio::io::{AsyncBufReadExt, AsyncWriteExt, BufReader};
 use tokio::process::{Child, Command};
-use tokio::sync::{mpsc, Mutex};
+use tokio::sync::mpsc;
 
 pub use commands::{CommandContext, StreamChunk};
 pub use shell_parser::{parse_shell_command, needs_real_shell, ParsedCommand};
-pub use utils::{AnsiConfig, AnsiUtils, CommandResult, VirtualUtils, quote, trace};
+pub use utils::{CommandResult, VirtualUtils};
+
+// Re-export modular utilities at crate root for convenient access
+pub use ansi::{AnsiConfig, AnsiUtils};
+pub use events::{EventData, EventType, StreamEmitter};
+pub use pipeline::{Pipeline, PipelineExt, PipelineBuilder};
+pub use quote::quote;
+pub use state::{global_state, reset_global_state, get_shell_settings, set_shell_option, unset_shell_option, GlobalState, ShellSettings};
+pub use stream::{StreamingRunner, OutputStream, OutputChunk, AsyncIterator, IntoStream};
+pub use trace::trace;
 
 /// Error type for command-stream operations
 #[derive(Debug, thiserror::Error)]
@@ -66,21 +119,6 @@ pub enum Error {
 /// Result type for command-stream operations
 pub type Result<T> = std::result::Result<T, Error>;
 
-/// Shell settings for controlling execution behavior
-#[derive(Debug, Clone, Default)]
-pub struct ShellSettings {
-    /// Exit immediately if a command exits with non-zero status (set -e)
-    pub errexit: bool,
-    /// Print commands as they are executed (set -v)
-    pub verbose: bool,
-    /// Print trace of commands (set -x)
-    pub xtrace: bool,
-    /// Return value of a pipeline is the status of the last command to exit with non-zero (set -o pipefail)
-    pub pipefail: bool,
-    /// Treat unset variables as an error (set -u)
-    pub nounset: bool,
-}
-
 /// Options for command execution
 #[derive(Debug, Clone)]
 pub struct RunOptions {
@@ -179,8 +217,8 @@ impl ProcessRunner {
             return Ok(());
         }
 
-        // Parse command for shell operators
-        let parsed = if self.options.shell_operators && !needs_real_shell(&self.command) {
+        // Parse command for shell operators (for future use with virtual command pipelines)
+        let _parsed = if self.options.shell_operators && !needs_real_shell(&self.command) {
             parse_shell_command(&self.command)
         } else {
             None
@@ -364,6 +402,16 @@ impl ProcessRunner {
     pub fn result(&self) -> Option<&CommandResult> {
         self.result.as_ref()
     }
+
+    /// Get the command string
+    pub fn command(&self) -> &str {
+        &self.command
+    }
+
+    /// Get the options
+    pub fn options(&self) -> &RunOptions {
+        &self.options
+    }
 }
 
 /// Shell configuration
@@ -452,41 +500,4 @@ pub fn run_sync(command: impl Into<String>) -> Result<CommandResult> {
     rt.block_on(run(command))
 }
 
-#[cfg(test)]
-mod tests {
-    use super::*;
-
-    #[tokio::test]
-    async fn test_simple_echo() {
-        let result = run("echo hello").await.unwrap();
-        assert!(result.is_success());
-        assert!(result.stdout.contains("hello"));
-    }
-
-    #[tokio::test]
-    async fn test_virtual_echo() {
-        let mut runner = ProcessRunner::new("echo test virtual", RunOptions::default());
-        let result = runner.run().await.unwrap();
-        assert!(result.is_success());
-        assert!(result.stdout.contains("test virtual"));
-    }
-
-    #[tokio::test]
-    async fn test_process_runner() {
-        let mut runner = ProcessRunner::new("echo hello world", RunOptions {
-            mirror: false,
-            ..Default::default()
-        });
-
-        let result = runner.run().await.unwrap();
-        assert!(result.is_success());
-    }
-
-    #[tokio::test]
-    async fn test_virtual_pwd() {
-        let mut runner = ProcessRunner::new("pwd", RunOptions::default());
-        let result = runner.run().await.unwrap();
-        assert!(result.is_success());
-        assert!(!result.stdout.is_empty());
-    }
-}
+// Tests are located in tests/ directory for better organization