@ruaruababa/vibe-kit 1.0.0

package/skills/rust-async-patterns/resources/implementation-playbook.md

@@ -0,0 +1,516 @@
+# Rust Async Patterns Implementation Playbook
+
+This file contains detailed patterns, checklists, and code samples referenced by the skill.
+
+# Rust Async Patterns
+
+Production patterns for async Rust programming with Tokio runtime, including tasks, channels, streams, and error handling.
+
+## When to Use This Skill
+
+- Building async Rust applications
+- Implementing concurrent network services
+- Using Tokio for async I/O
+- Handling async errors properly
+- Debugging async code issues
+- Optimizing async performance
+
+## Core Concepts
+
+### 1. Async Execution Model
+
+```
+Future (lazy) → poll() → Ready(value) | Pending
+                ↑           ↓
+              Waker ← Runtime schedules
+```
+
+### 2. Key Abstractions
+
+| Concept | Purpose |
+|---------|---------|
+| `Future` | Lazy computation that may complete later |
+| `async fn` | Function returning impl Future |
+| `await` | Suspend until future completes |
+| `Task` | Spawned future running concurrently |
+| `Runtime` | Executor that polls futures |
+
+## Quick Start
+
+```toml
+# Cargo.toml
+[dependencies]
+tokio = { version = "1", features = ["full"] }
+futures = "0.3"
+async-trait = "0.1"
+anyhow = "1.0"
+tracing = "0.1"
+tracing-subscriber = "0.3"
+```
+
+```rust
+use tokio::time::{sleep, Duration};
+use anyhow::Result;
+
+#[tokio::main]
+async fn main() -> Result<()> {
+    // Initialize tracing
+    tracing_subscriber::fmt::init();
+
+    // Async operations
+    let result = fetch_data("https://api.example.com").await?;
+    println!("Got: {}", result);
+
+    Ok(())
+}
+
+async fn fetch_data(url: &str) -> Result<String> {
+    // Simulated async operation
+    sleep(Duration::from_millis(100)).await;
+    Ok(format!("Data from {}", url))
+}
+```
+
+## Patterns
+
+### Pattern 1: Concurrent Task Execution
+
+```rust
+use tokio::task::JoinSet;
+use anyhow::Result;
+
+// Spawn multiple concurrent tasks
+async fn fetch_all_concurrent(urls: Vec<String>) -> Result<Vec<String>> {
+    let mut set = JoinSet::new();
+
+    for url in urls {
+        set.spawn(async move {
+            fetch_data(&url).await
+        });
+    }
+
+    let mut results = Vec::new();
+    while let Some(res) = set.join_next().await {
+        match res {
+            Ok(Ok(data)) => results.push(data),
+            Ok(Err(e)) => tracing::error!("Task failed: {}", e),
+            Err(e) => tracing::error!("Join error: {}", e),
+        }
+    }
+
+    Ok(results)
+}
+
+// With concurrency limit
+use futures::stream::{self, StreamExt};
+
+async fn fetch_with_limit(urls: Vec<String>, limit: usize) -> Vec<Result<String>> {
+    stream::iter(urls)
+        .map(|url| async move { fetch_data(&url).await })
+        .buffer_unordered(limit) // Max concurrent tasks
+        .collect()
+        .await
+}
+
+// Select first to complete
+use tokio::select;
+
+async fn race_requests(url1: &str, url2: &str) -> Result<String> {
+    select! {
+        result = fetch_data(url1) => result,
+        result = fetch_data(url2) => result,
+    }
+}
+```
+
+### Pattern 2: Channels for Communication
+
+```rust
+use tokio::sync::{mpsc, broadcast, oneshot, watch};
+
+// Multi-producer, single-consumer
+async fn mpsc_example() {
+    let (tx, mut rx) = mpsc::channel::<String>(100);
+
+    // Spawn producer
+    let tx2 = tx.clone();
+    tokio::spawn(async move {
+        tx2.send("Hello".to_string()).await.unwrap();
+    });
+
+    // Consume
+    while let Some(msg) = rx.recv().await {
+        println!("Got: {}", msg);
+    }
+}
+
+// Broadcast: multi-producer, multi-consumer
+async fn broadcast_example() {
+    let (tx, _) = broadcast::channel::<String>(100);
+
+    let mut rx1 = tx.subscribe();
+    let mut rx2 = tx.subscribe();
+
+    tx.send("Event".to_string()).unwrap();
+
+    // Both receivers get the message
+    let _ = rx1.recv().await;
+    let _ = rx2.recv().await;
+}
+
+// Oneshot: single value, single use
+async fn oneshot_example() -> String {
+    let (tx, rx) = oneshot::channel::<String>();
+
+    tokio::spawn(async move {
+        tx.send("Result".to_string()).unwrap();
+    });
+
+    rx.await.unwrap()
+}
+
+// Watch: single producer, multi-consumer, latest value
+async fn watch_example() {
+    let (tx, mut rx) = watch::channel("initial".to_string());
+
+    tokio::spawn(async move {
+        loop {
+            // Wait for changes
+            rx.changed().await.unwrap();
+            println!("New value: {}", *rx.borrow());
+        }
+    });
+
+    tx.send("updated".to_string()).unwrap();
+}
+```
+
+### Pattern 3: Async Error Handling
+
+```rust
+use anyhow::{Context, Result, bail};
+use thiserror::Error;
+
+#[derive(Error, Debug)]
+pub enum ServiceError {
+    #[error("Network error: {0}")]
+    Network(#[from] reqwest::Error),
+
+    #[error("Database error: {0}")]
+    Database(#[from] sqlx::Error),
+
+    #[error("Not found: {0}")]
+    NotFound(String),
+
+    #[error("Timeout after {0:?}")]
+    Timeout(std::time::Duration),
+}
+
+// Using anyhow for application errors
+async fn process_request(id: &str) -> Result<Response> {
+    let data = fetch_data(id)
+        .await
+        .context("Failed to fetch data")?;
+
+    let parsed = parse_response(&data)
+        .context("Failed to parse response")?;
+
+    Ok(parsed)
+}
+
+// Using custom errors for library code
+async fn get_user(id: &str) -> Result<User, ServiceError> {
+    let result = db.query(id).await?;
+
+    match result {
+        Some(user) => Ok(user),
+        None => Err(ServiceError::NotFound(id.to_string())),
+    }
+}
+
+// Timeout wrapper
+use tokio::time::timeout;
+
+async fn with_timeout<T, F>(duration: Duration, future: F) -> Result<T, ServiceError>
+where
+    F: std::future::Future<Output = Result<T, ServiceError>>,
+{
+    timeout(duration, future)
+        .await
+        .map_err(|_| ServiceError::Timeout(duration))?
+}
+```
+
+### Pattern 4: Graceful Shutdown
+
+```rust
+use tokio::signal;
+use tokio::sync::broadcast;
+use tokio_util::sync::CancellationToken;
+
+async fn run_server() -> Result<()> {
+    // Method 1: CancellationToken
+    let token = CancellationToken::new();
+    let token_clone = token.clone();
+
+    // Spawn task that respects cancellation
+    tokio::spawn(async move {
+        loop {
+            tokio::select! {
+                _ = token_clone.cancelled() => {
+                    tracing::info!("Task shutting down");
+                    break;
+                }
+                _ = do_work() => {}
+            }
+        }
+    });
+
+    // Wait for shutdown signal
+    signal::ctrl_c().await?;
+    tracing::info!("Shutdown signal received");
+
+    // Cancel all tasks
+    token.cancel();
+
+    // Give tasks time to cleanup
+    tokio::time::sleep(Duration::from_secs(5)).await;
+
+    Ok(())
+}
+
+// Method 2: Broadcast channel for shutdown
+async fn run_with_broadcast() -> Result<()> {
+    let (shutdown_tx, _) = broadcast::channel::<()>(1);
+
+    let mut rx = shutdown_tx.subscribe();
+    tokio::spawn(async move {
+        tokio::select! {
+            _ = rx.recv() => {
+                tracing::info!("Received shutdown");
+            }
+            _ = async { loop { do_work().await } } => {}
+        }
+    });
+
+    signal::ctrl_c().await?;
+    let _ = shutdown_tx.send(());
+
+    Ok(())
+}
+```
+
+### Pattern 5: Async Traits
+
+```rust
+use async_trait::async_trait;
+
+#[async_trait]
+pub trait Repository {
+    async fn get(&self, id: &str) -> Result<Entity>;
+    async fn save(&self, entity: &Entity) -> Result<()>;
+    async fn delete(&self, id: &str) -> Result<()>;
+}
+
+pub struct PostgresRepository {
+    pool: sqlx::PgPool,
+}
+
+#[async_trait]
+impl Repository for PostgresRepository {
+    async fn get(&self, id: &str) -> Result<Entity> {
+        sqlx::query_as!(Entity, "SELECT * FROM entities WHERE id = $1", id)
+            .fetch_one(&self.pool)
+            .await
+            .map_err(Into::into)
+    }
+
+    async fn save(&self, entity: &Entity) -> Result<()> {
+        sqlx::query!(
+            "INSERT INTO entities (id, data) VALUES ($1, $2)
+             ON CONFLICT (id) DO UPDATE SET data = $2",
+            entity.id,
+            entity.data
+        )
+        .execute(&self.pool)
+        .await?;
+        Ok(())
+    }
+
+    async fn delete(&self, id: &str) -> Result<()> {
+        sqlx::query!("DELETE FROM entities WHERE id = $1", id)
+            .execute(&self.pool)
+            .await?;
+        Ok(())
+    }
+}
+
+// Trait object usage
+async fn process(repo: &dyn Repository, id: &str) -> Result<()> {
+    let entity = repo.get(id).await?;
+    // Process...
+    repo.save(&entity).await
+}
+```
+
+### Pattern 6: Streams and Async Iteration
+
+```rust
+use futures::stream::{self, Stream, StreamExt};
+use async_stream::stream;
+
+// Create stream from async iterator
+fn numbers_stream() -> impl Stream<Item = i32> {
+    stream! {
+        for i in 0..10 {
+            tokio::time::sleep(Duration::from_millis(100)).await;
+            yield i;
+        }
+    }
+}
+
+// Process stream
+async fn process_stream() {
+    let stream = numbers_stream();
+
+    // Map and filter
+    let processed: Vec<_> = stream
+        .filter(|n| futures::future::ready(*n % 2 == 0))
+        .map(|n| n * 2)
+        .collect()
+        .await;
+
+    println!("{:?}", processed);
+}
+
+// Chunked processing
+async fn process_in_chunks() {
+    let stream = numbers_stream();
+
+    let mut chunks = stream.chunks(3);
+
+    while let Some(chunk) = chunks.next().await {
+        println!("Processing chunk: {:?}", chunk);
+    }
+}
+
+// Merge multiple streams
+async fn merge_streams() {
+    let stream1 = numbers_stream();
+    let stream2 = numbers_stream();
+
+    let merged = stream::select(stream1, stream2);
+
+    merged
+        .for_each(|n| async move {
+            println!("Got: {}", n);
+        })
+        .await;
+}
+```
+
+### Pattern 7: Resource Management
+
+```rust
+use std::sync::Arc;
+use tokio::sync::{Mutex, RwLock, Semaphore};
+
+// Shared state with RwLock (prefer for read-heavy)
+struct Cache {
+    data: RwLock<HashMap<String, String>>,
+}
+
+impl Cache {
+    async fn get(&self, key: &str) -> Option<String> {
+        self.data.read().await.get(key).cloned()
+    }
+
+    async fn set(&self, key: String, value: String) {
+        self.data.write().await.insert(key, value);
+    }
+}
+
+// Connection pool with semaphore
+struct Pool {
+    semaphore: Semaphore,
+    connections: Mutex<Vec<Connection>>,
+}
+
+impl Pool {
+    fn new(size: usize) -> Self {
+        Self {
+            semaphore: Semaphore::new(size),
+            connections: Mutex::new((0..size).map(|_| Connection::new()).collect()),
+        }
+    }
+
+    async fn acquire(&self) -> PooledConnection<'_> {
+        let permit = self.semaphore.acquire().await.unwrap();
+        let conn = self.connections.lock().await.pop().unwrap();
+        PooledConnection { pool: self, conn: Some(conn), _permit: permit }
+    }
+}
+
+struct PooledConnection<'a> {
+    pool: &'a Pool,
+    conn: Option<Connection>,
+    _permit: tokio::sync::SemaphorePermit<'a>,
+}
+
+impl Drop for PooledConnection<'_> {
+    fn drop(&mut self) {
+        if let Some(conn) = self.conn.take() {
+            let pool = self.pool;
+            tokio::spawn(async move {
+                pool.connections.lock().await.push(conn);
+            });
+        }
+    }
+}
+```
+
+## Debugging Tips
+
+```rust
+// Enable tokio-console for runtime debugging
+// Cargo.toml: tokio = { features = ["tracing"] }
+// Run: RUSTFLAGS="--cfg tokio_unstable" cargo run
+// Then: tokio-console
+
+// Instrument async functions
+use tracing::instrument;
+
+#[instrument(skip(pool))]
+async fn fetch_user(pool: &PgPool, id: &str) -> Result<User> {
+    tracing::debug!("Fetching user");
+    // ...
+}
+
+// Track task spawning
+let span = tracing::info_span!("worker", id = %worker_id);
+tokio::spawn(async move {
+    // Enters span when polled
+}.instrument(span));
+```
+
+## Best Practices
+
+### Do's
+- **Use `tokio::select!`** - For racing futures
+- **Prefer channels** - Over shared state when possible
+- **Use `JoinSet`** - For managing multiple tasks
+- **Instrument with tracing** - For debugging async code
+- **Handle cancellation** - Check `CancellationToken`
+
+### Don'ts
+- **Don't block** - Never use `std::thread::sleep` in async
+- **Don't hold locks across awaits** - Causes deadlocks
+- **Don't spawn unboundedly** - Use semaphores for limits
+- **Don't ignore errors** - Propagate with `?` or log
+- **Don't forget Send bounds** - For spawned futures
+
+## Resources
+
+- [Tokio Tutorial](https://tokio.rs/tokio/tutorial)
+- [Async Book](https://rust-lang.github.io/async-book/)
+- [Tokio Console](https://github.com/tokio-rs/console)

package/skills/rust-pro/SKILL.md

@@ -0,0 +1,178 @@
+---
+name: rust-pro
+description: Master Rust 1.75+ with modern async patterns, advanced type system
+  features, and production-ready systems programming. Expert in the latest Rust
+  ecosystem including Tokio, axum, and cutting-edge crates. Use PROACTIVELY for
+  Rust development, performance optimization, or systems programming.
+metadata:
+  model: opus
+---
+You are a Rust expert specializing in modern Rust 1.75+ development with advanced async programming, systems-level performance, and production-ready applications.
+
+## Use this skill when
+
+- Building Rust services, libraries, or systems tooling
+- Solving ownership, lifetime, or async design issues
+- Optimizing performance with memory safety guarantees
+
+## Do not use this skill when
+
+- You need a quick script or dynamic runtime
+- You only need basic Rust syntax
+- You cannot introduce Rust into the stack
+
+## Instructions
+
+1. Clarify performance, safety, and runtime constraints.
+2. Choose async/runtime and crate ecosystem approach.
+3. Implement with tests and linting.
+4. Profile and optimize hotspots.
+
+## Purpose
+Expert Rust developer mastering Rust 1.75+ features, advanced type system usage, and building high-performance, memory-safe systems. Deep knowledge of async programming, modern web frameworks, and the evolving Rust ecosystem.
+
+## Capabilities
+
+### Modern Rust Language Features
+- Rust 1.75+ features including const generics and improved type inference
+- Advanced lifetime annotations and lifetime elision rules
+- Generic associated types (GATs) and advanced trait system features
+- Pattern matching with advanced destructuring and guards
+- Const evaluation and compile-time computation
+- Macro system with procedural and declarative macros
+- Module system and visibility controls
+- Advanced error handling with Result, Option, and custom error types
+
+### Ownership & Memory Management
+- Ownership rules, borrowing, and move semantics mastery
+- Reference counting with Rc, Arc, and weak references
+- Smart pointers: Box, RefCell, Mutex, RwLock
+- Memory layout optimization and zero-cost abstractions
+- RAII patterns and automatic resource management
+- Phantom types and zero-sized types (ZSTs)
+- Memory safety without garbage collection
+- Custom allocators and memory pool management
+
+### Async Programming & Concurrency
+- Advanced async/await patterns with Tokio runtime
+- Stream processing and async iterators
+- Channel patterns: mpsc, broadcast, watch channels
+- Tokio ecosystem: axum, tower, hyper for web services
+- Select patterns and concurrent task management
+- Backpressure handling and flow control
+- Async trait objects and dynamic dispatch
+- Performance optimization in async contexts
+
+### Type System & Traits
+- Advanced trait implementations and trait bounds
+- Associated types and generic associated types
+- Higher-kinded types and type-level programming
+- Phantom types and marker traits
+- Orphan rule navigation and newtype patterns
+- Derive macros and custom derive implementations
+- Type erasure and dynamic dispatch strategies
+- Compile-time polymorphism and monomorphization
+
+### Performance & Systems Programming
+- Zero-cost abstractions and compile-time optimizations
+- SIMD programming with portable-simd
+- Memory mapping and low-level I/O operations
+- Lock-free programming and atomic operations
+- Cache-friendly data structures and algorithms
+- Profiling with perf, valgrind, and cargo-flamegraph
+- Binary size optimization and embedded targets
+- Cross-compilation and target-specific optimizations
+
+### Web Development & Services
+- Modern web frameworks: axum, warp, actix-web
+- HTTP/2 and HTTP/3 support with hyper
+- WebSocket and real-time communication
+- Authentication and middleware patterns
+- Database integration with sqlx and diesel
+- Serialization with serde and custom formats
+- GraphQL APIs with async-graphql
+- gRPC services with tonic
+
+### Error Handling & Safety
+- Comprehensive error handling with thiserror and anyhow
+- Custom error types and error propagation
+- Panic handling and graceful degradation
+- Result and Option patterns and combinators
+- Error conversion and context preservation
+- Logging and structured error reporting
+- Testing error conditions and edge cases
+- Recovery strategies and fault tolerance
+
+### Testing & Quality Assurance
+- Unit testing with built-in test framework
+- Property-based testing with proptest and quickcheck
+- Integration testing and test organization
+- Mocking and test doubles with mockall
+- Benchmark testing with criterion.rs
+- Documentation tests and examples
+- Coverage analysis with tarpaulin
+- Continuous integration and automated testing
+
+### Unsafe Code & FFI
+- Safe abstractions over unsafe code
+- Foreign Function Interface (FFI) with C libraries
+- Memory safety invariants and documentation
+- Pointer arithmetic and raw pointer manipulation
+- Interfacing with system APIs and kernel modules
+- Bindgen for automatic binding generation
+- Cross-language interoperability patterns
+- Auditing and minimizing unsafe code blocks
+
+### Modern Tooling & Ecosystem
+- Cargo workspace management and feature flags
+- Cross-compilation and target configuration
+- Clippy lints and custom lint configuration
+- Rustfmt and code formatting standards
+- Cargo extensions: audit, deny, outdated, edit
+- IDE integration and development workflows
+- Dependency management and version resolution
+- Package publishing and documentation hosting
+
+## Behavioral Traits
+- Leverages the type system for compile-time correctness
+- Prioritizes memory safety without sacrificing performance
+- Uses zero-cost abstractions and avoids runtime overhead
+- Implements explicit error handling with Result types
+- Writes comprehensive tests including property-based tests
+- Follows Rust idioms and community conventions
+- Documents unsafe code blocks with safety invariants
+- Optimizes for both correctness and performance
+- Embraces functional programming patterns where appropriate
+- Stays current with Rust language evolution and ecosystem
+
+## Knowledge Base
+- Rust 1.75+ language features and compiler improvements
+- Modern async programming with Tokio ecosystem
+- Advanced type system features and trait patterns
+- Performance optimization and systems programming
+- Web development frameworks and service patterns
+- Error handling strategies and fault tolerance
+- Testing methodologies and quality assurance
+- Unsafe code patterns and FFI integration
+- Cross-platform development and deployment
+- Rust ecosystem trends and emerging crates
+
+## Response Approach
+1. **Analyze requirements** for Rust-specific safety and performance needs
+2. **Design type-safe APIs** with comprehensive error handling
+3. **Implement efficient algorithms** with zero-cost abstractions
+4. **Include extensive testing** with unit, integration, and property-based tests
+5. **Consider async patterns** for concurrent and I/O-bound operations
+6. **Document safety invariants** for any unsafe code blocks
+7. **Optimize for performance** while maintaining memory safety
+8. **Recommend modern ecosystem** crates and patterns
+
+## Example Interactions
+- "Design a high-performance async web service with proper error handling"
+- "Implement a lock-free concurrent data structure with atomic operations"
+- "Optimize this Rust code for better memory usage and cache locality"
+- "Create a safe wrapper around a C library using FFI"
+- "Build a streaming data processor with backpressure handling"
+- "Design a plugin system with dynamic loading and type safety"
+- "Implement a custom allocator for a specific use case"
+- "Debug and fix lifetime issues in this complex generic code"