ensembler/
lib.rs

1//! # ensembler
2//!
3//! A library for executing external commands with advanced output handling
4//! and progress reporting capabilities.
5//!
6//! ## Features
7//!
8//! - **Async execution** - Built on Tokio for non-blocking command execution
9//! - **Output capture** - Capture stdout, stderr, and combined output
10//! - **Progress integration** - Real-time progress bar updates via the `clx` crate
11//! - **Secret redaction** - Automatically redact sensitive data from output
12//! - **Cancellation** - Support for cancelling running commands via `CancellationToken`
13//! - **Cross-platform** - Works on Unix and Windows
14//!
15//! ## Basic Usage
16//!
17//! > **Note:** Examples use Unix commands for clarity. On Windows, substitute
18//! > equivalent commands (e.g., `dir` for `ls`, `type` for `cat`).
19//!
20//! ```no_run
21//! use ensembler::CmdLineRunner;
22//!
23//! #[tokio::main]
24//! async fn main() -> ensembler::Result<()> {
25//!     let result = CmdLineRunner::new("echo")
26//!         .arg("hello")
27//!         .execute()
28//!         .await?;
29//!
30//!     println!("stdout: {}", result.stdout);
31//!     Ok(())
32//! }
33//! ```
34//!
35//! ## Redacting Secrets
36//!
37//! Sensitive data can be automatically redacted from command output:
38//!
39//! ```no_run
40//! use ensembler::CmdLineRunner;
41//!
42//! #[tokio::main]
43//! async fn main() -> ensembler::Result<()> {
44//!     let api_key = "super-secret-key";
45//!     let result = CmdLineRunner::new("echo")
46//!         .arg(api_key)
47//!         .redact(vec![api_key.to_string()])
48//!         .execute()
49//!         .await?;
50//!
51//!     // stdout will contain "[redacted]" instead of the actual key
52//!     assert!(!result.stdout.contains(api_key));
53//!     Ok(())
54//! }
55//! ```
56//!
57//! ## Stdin Input
58//!
59//! Pipe input to a command's stdin:
60//!
61//! ```no_run
62//! use ensembler::CmdLineRunner;
63//!
64//! #[tokio::main]
65//! async fn main() -> ensembler::Result<()> {
66//!     let result = CmdLineRunner::new("cat")
67//!         .stdin_string("hello from stdin")
68//!         .execute()
69//!         .await?;
70//!
71//!     assert_eq!(result.stdout.trim(), "hello from stdin");
72//!     Ok(())
73//! }
74//! ```
75//!
76//! ## Cancellation
77//!
78//! Commands can be cancelled using a `CancellationToken`:
79//!
80//! ```no_run
81//! use ensembler::CmdLineRunner;
82//! use tokio_util::sync::CancellationToken;
83//! use std::time::Duration;
84//!
85//! #[tokio::main]
86//! async fn main() -> ensembler::Result<()> {
87//!     let cancel = CancellationToken::new();
88//!     let cancel_clone = cancel.clone();
89//!
90//!     // Cancel after 1 second
91//!     tokio::spawn(async move {
92//!         tokio::time::sleep(Duration::from_secs(1)).await;
93//!         cancel_clone.cancel();
94//!     });
95//!
96//!     let result = CmdLineRunner::new("sleep")
97//!         .arg("60")
98//!         .with_cancel_token(cancel)
99//!         .execute()
100//!         .await;
101//!
102//!     // Command was cancelled
103//!     assert!(result.is_err());
104//!     Ok(())
105//! }
106//! ```
107
108#[macro_use]
109extern crate log;
110mod cmd;
111mod error;
112
113pub use cmd::{CmdLineRunner, CmdResult};
114pub use error::{Error, Result};
ensembler/lib.rs

ensembler/
lib.rs
