shell_tunnel/lib.rs
1//! # shell-tunnel
2//!
3//! Ultra-lightweight shell tunnel for AI agent integration.
4//!
5//! This crate provides a secure, cross-platform API for AI agents to
6//! interact with system shells. It supports both Windows (ConPTY) and
7//! Unix (PTY) terminals through a unified interface.
8//!
9//! ## Features
10//!
11//! - **Cross-platform PTY**: Unified interface for Windows ConPTY and Unix PTY
12//! - **Async I/O**: Non-blocking operations using tokio
13//! - **Session Management**: Stateful shell sessions with lifecycle tracking
14//! - **REST API**: HTTP endpoints for command execution
15//! - **WebSocket**: Real-time streaming of command output
16//! - **Lightweight**: Minimal dependencies, small binary size
17//!
18//! ## Quick Start
19//!
20//! ```no_run
21//! use shell_tunnel::{NativePty, PtySize, SessionStore, SessionConfig};
22//!
23//! #[tokio::main]
24//! async fn main() -> shell_tunnel::Result<()> {
25//! // Initialize logging
26//! shell_tunnel::logging::try_init().ok();
27//!
28//! // Create a session store
29//! let store = SessionStore::new();
30//!
31//! // Create a new session
32//! let session_id = store.create(SessionConfig::default())?;
33//!
34//! // Spawn a PTY
35//! let pty = NativePty::new();
36//! let handle = pty.spawn_default(PtySize::default())?;
37//!
38//! println!("Session {} created with PID {}", session_id, handle.pid);
39//!
40//! Ok(())
41//! }
42//! ```
43//!
44//! ## API Server
45//!
46//! ```no_run
47//! use shell_tunnel::api::{ServerConfig, serve};
48//!
49//! #[tokio::main]
50//! async fn main() -> shell_tunnel::Result<()> {
51//! shell_tunnel::logging::try_init().ok();
52//! let config = ServerConfig::new("127.0.0.1", 3000);
53//! serve(config).await
54//! }
55//! ```
56
57pub mod api;
58pub mod cli;
59pub mod config;
60pub mod error;
61pub mod execution;
62pub mod logging;
63pub mod output;
64pub mod pty;
65pub mod security;
66pub mod session;
67#[cfg(feature = "self-update")]
68pub mod update;
69
70// Re-export commonly used types
71pub use error::{Result, ShellTunnelError};
72pub use execution::{Command, CommandExecutor, ExecutionResult};
73pub use output::{OutputSanitizer, VirtualScreen};
74pub use pty::{AsyncPtyReader, AsyncPtyWriter, NativePty, PtyHandle, PtySize};
75pub use session::{
76 Session, SessionConfig, SessionContext, SessionId, SessionState, SessionStore, StateProbe,
77};
78
79// Re-export API types
80pub use api::{AppState, ServerConfig};
81
82// Re-export security types
83pub use security::{
84 ApiKeyStore, AuthConfig, CapabilitySet, CommandValidator, RateLimiter, TokenRecord,
85 ValidationConfig,
86};
87
88// Re-export CLI and config types
89pub use cli::{parse_args, print_help, print_version, Args};
90pub use config::{Config, ConfigError};