agy-superpowers 5.1.4 → 5.1.6

package/template/agent/skills/rust-developer/references/rust-rules/async-tokio-fs.md

@@ -0,0 +1,167 @@
+# async-tokio-fs
+
+> Use `tokio::fs` instead of `std::fs` in async code
+
+## Why It Matters
+
+`std::fs` operations are blocking—they stop the current thread until the syscall completes. In async code, this blocks the executor thread, preventing it from running other tasks. `tokio::fs` wraps filesystem operations in `spawn_blocking`, keeping the executor responsive.
+
+## Bad
+
+```rust
+async fn process_files(paths: &[PathBuf]) -> Result<Vec<String>> {
+    let mut contents = Vec::new();
+    
+    for path in paths {
+        // BLOCKS the entire executor thread!
+        let data = std::fs::read_to_string(path)?;
+        contents.push(data);
+    }
+    
+    Ok(contents)
+}
+
+// While reading a file, NO other tasks can run on this thread
+```
+
+## Good
+
+```rust
+use tokio::fs;
+
+async fn process_files(paths: &[PathBuf]) -> Result<Vec<String>> {
+    let mut contents = Vec::new();
+    
+    for path in paths {
+        // Non-blocking: allows other tasks to run
+        let data = fs::read_to_string(path).await?;
+        contents.push(data);
+    }
+    
+    Ok(contents)
+}
+
+// Even better: concurrent reads
+async fn process_files_concurrent(paths: &[PathBuf]) -> Result<Vec<String>> {
+    let futures: Vec<_> = paths.iter()
+        .map(|path| fs::read_to_string(path))
+        .collect();
+    
+    futures::future::try_join_all(futures).await
+}
+```
+
+## tokio::fs API
+
+```rust
+use tokio::fs;
+
+// Reading
+let contents = fs::read_to_string("file.txt").await?;
+let bytes = fs::read("file.bin").await?;
+
+// Writing
+fs::write("output.txt", "contents").await?;
+
+// File operations
+let file = fs::File::open("file.txt").await?;
+let file = fs::File::create("new.txt").await?;
+
+// Directory operations
+fs::create_dir("new_dir").await?;
+fs::create_dir_all("nested/dir/path").await?;
+fs::remove_dir("empty_dir").await?;
+fs::remove_dir_all("dir_with_contents").await?;
+
+// Metadata
+let metadata = fs::metadata("file.txt").await?;
+let canonical = fs::canonicalize("./relative").await?;
+
+// Rename/remove
+fs::rename("old.txt", "new.txt").await?;
+fs::remove_file("file.txt").await?;
+
+// Read directory
+let mut entries = fs::read_dir("some_dir").await?;
+while let Some(entry) = entries.next_entry().await? {
+    println!("{}", entry.path().display());
+}
+```
+
+## Async File I/O
+
+```rust
+use tokio::fs::File;
+use tokio::io::{AsyncReadExt, AsyncWriteExt, AsyncBufReadExt, BufReader};
+
+// Read with buffer
+let mut file = File::open("large.bin").await?;
+let mut buffer = vec![0u8; 4096];
+let bytes_read = file.read(&mut buffer).await?;
+
+// Read all
+let mut contents = Vec::new();
+file.read_to_end(&mut contents).await?;
+
+// Write
+let mut file = File::create("output.bin").await?;
+file.write_all(b"data").await?;
+file.flush().await?;
+
+// Buffered line reading
+let file = File::open("lines.txt").await?;
+let reader = BufReader::new(file);
+let mut lines = reader.lines();
+
+while let Some(line) = lines.next_line().await? {
+    println!("{}", line);
+}
+```
+
+## When std::fs is Acceptable
+
+```rust
+// Startup/initialization (before async runtime)
+fn main() {
+    let config = std::fs::read_to_string("config.toml")
+        .expect("config file required");
+    
+    tokio::runtime::Runtime::new()
+        .unwrap()
+        .block_on(run_with_config(config));
+}
+
+// Single-threaded current_thread runtime (less impact)
+#[tokio::main(flavor = "current_thread")]
+async fn main() {
+    // Still prefer tokio::fs, but impact is lower
+}
+
+// When file operations are rare and quick
+// (e.g., reading small config once per hour)
+```
+
+## Performance Considerations
+
+```rust
+// tokio::fs uses spawn_blocking internally
+// For many small files, the overhead adds up
+
+// Batch operations when possible
+let paths: Vec<_> = entries.iter()
+    .map(|e| e.path())
+    .collect();
+
+let contents = futures::future::try_join_all(
+    paths.iter().map(|p| fs::read_to_string(p))
+).await?;
+
+// For heavy I/O, consider memory-mapped files
+// (requires unsafe or mmap crate)
+```
+
+## See Also
+
+- [async-spawn-blocking](./async-spawn-blocking.md) - How tokio::fs works internally
+- [async-tokio-runtime](./async-tokio-runtime.md) - Runtime configuration
+- [err-context-chain](./err-context-chain.md) - Adding path context to IO errors

package/template/agent/skills/rust-developer/references/rust-rules/async-tokio-runtime.md

@@ -0,0 +1,169 @@
+# async-tokio-runtime
+
+> Configure Tokio runtime appropriately for your workload
+
+## Why It Matters
+
+Tokio's default multi-threaded runtime isn't always optimal. CPU-bound work needs different configuration than IO-bound work. Incorrect configuration leads to poor performance, blocked workers, or resource exhaustion. Understanding runtime options lets you tune for your specific use case.
+
+## Bad
+
+```rust
+// Default runtime for everything - not optimal
+#[tokio::main]
+async fn main() {
+    // CPU-heavy work on async executor starves IO tasks
+    for data in datasets {
+        let result = heavy_computation(data).await;
+    }
+}
+
+// Single-threaded when multi-threaded is needed
+#[tokio::main(flavor = "current_thread")]
+async fn main() {
+    // Can't utilize multiple cores for concurrent tasks
+    for _ in 0..1000 {
+        tokio::spawn(async { /* IO work */ });
+    }
+}
+```
+
+## Good
+
+```rust
+// Multi-threaded for concurrent IO (default)
+#[tokio::main]
+async fn main() {
+    // Good for many concurrent network connections
+    let handles: Vec<_> = urls.iter()
+        .map(|url| tokio::spawn(fetch(url.clone())))
+        .collect();
+    
+    futures::future::join_all(handles).await;
+}
+
+// Current-thread for single-threaded scenarios
+#[tokio::main(flavor = "current_thread")]
+async fn main() {
+    // Good for single-connection clients, simpler debugging
+    let client = Client::new();
+    client.run().await;
+}
+
+// Custom configuration
+#[tokio::main(worker_threads = 4)]
+async fn main() {
+    // Limit to 4 worker threads
+}
+
+// Or manual setup for more control
+fn main() {
+    let runtime = tokio::runtime::Builder::new_multi_thread()
+        .worker_threads(4)
+        .enable_all()
+        .thread_name("my-worker")
+        .build()
+        .unwrap();
+    
+    runtime.block_on(async_main());
+}
+```
+
+## Runtime Types
+
+| Runtime | Use Case | Configuration |
+|---------|----------|---------------|
+| Multi-thread | IO-bound, many connections | `#[tokio::main]` (default) |
+| Current-thread | CLI tools, tests, single connection | `flavor = "current_thread"` |
+| Custom | Fine-tuned performance | `Builder::new_*()` |
+
+## Worker Thread Tuning
+
+```rust
+use tokio::runtime::Builder;
+
+// IO-bound: more threads than cores can help
+let io_runtime = Builder::new_multi_thread()
+    .worker_threads(num_cpus::get() * 2)  // IO can benefit from oversubscription
+    .max_blocking_threads(32)              // For spawn_blocking calls
+    .enable_io()
+    .enable_time()
+    .build()?;
+
+// CPU-bound: match core count
+let cpu_runtime = Builder::new_multi_thread()
+    .worker_threads(num_cpus::get())       // No benefit from more than cores
+    .build()?;
+```
+
+## Multiple Runtimes
+
+```rust
+// Separate runtimes for different workloads
+struct App {
+    io_runtime: Runtime,
+    cpu_runtime: Runtime,
+}
+
+impl App {
+    fn new() -> Self {
+        Self {
+            io_runtime: Builder::new_multi_thread()
+                .worker_threads(8)
+                .thread_name("io-worker")
+                .build()
+                .unwrap(),
+            cpu_runtime: Builder::new_multi_thread()
+                .worker_threads(4)
+                .thread_name("cpu-worker")
+                .build()
+                .unwrap(),
+        }
+    }
+    
+    fn spawn_io<F>(&self, future: F) 
+    where F: Future + Send + 'static, F::Output: Send + 'static 
+    {
+        self.io_runtime.spawn(future);
+    }
+    
+    fn spawn_cpu<F>(&self, task: F) 
+    where F: FnOnce() + Send + 'static 
+    {
+        self.cpu_runtime.spawn_blocking(task);
+    }
+}
+```
+
+## Runtime in Tests
+
+```rust
+// Single test runtime
+#[tokio::test]
+async fn test_single() {
+    assert!(true);
+}
+
+// Multi-threaded test
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn test_concurrent() {
+    let (tx, rx) = tokio::sync::oneshot::channel();
+    tokio::spawn(async move { tx.send(42).unwrap() });
+    assert_eq!(rx.await.unwrap(), 42);
+}
+
+// Custom runtime in test
+#[test]
+fn test_with_custom_runtime() {
+    let rt = Builder::new_current_thread().build().unwrap();
+    rt.block_on(async {
+        // test code
+    });
+}
+```
+
+## See Also
+
+- [async-spawn-blocking](./async-spawn-blocking.md) - Handling blocking code
+- [async-no-lock-await](./async-no-lock-await.md) - Avoiding lock issues
+- [async-joinset-structured](./async-joinset-structured.md) - Managing spawned tasks

package/template/agent/skills/rust-developer/references/rust-rules/async-try-join.md

@@ -0,0 +1,172 @@
+# async-try-join
+
+> Use `try_join!` for concurrent fallible operations with early return on error
+
+## Why It Matters
+
+When running multiple fallible operations concurrently, `try_join!` returns `Err` as soon as any future fails, without waiting for the others. This provides fail-fast behavior while still running operations in parallel. For many operations, use `futures::future::try_join_all`.
+
+## Bad
+
+```rust
+// Sequential - slow and no early return benefit
+async fn fetch_all() -> Result<(A, B, C)> {
+    let a = fetch_a().await?;  // If this fails, we wait for nothing
+    let b = fetch_b().await?;  // But if this fails, we waited for A
+    let c = fetch_c().await?;
+    Ok((a, b, c))
+}
+
+// join! ignores errors
+async fn fetch_all() -> (Result<A>, Result<B>, Result<C>) {
+    let (a, b, c) = join!(fetch_a(), fetch_b(), fetch_c());
+    // All complete even if first one failed
+    (a, b, c)  // Now we have to handle three Results
+}
+```
+
+## Good
+
+```rust
+use tokio::try_join;
+
+async fn fetch_all() -> Result<(A, B, C)> {
+    // Concurrent AND fail-fast
+    let (a, b, c) = try_join!(
+        fetch_a(),
+        fetch_b(),
+        fetch_c(),
+    )?;
+    
+    Ok((a, b, c))
+}
+
+// For dynamic collections
+use futures::future::try_join_all;
+
+async fn fetch_users(ids: &[u64]) -> Result<Vec<User>> {
+    let futures: Vec<_> = ids.iter()
+        .map(|id| fetch_user(*id))
+        .collect();
+    
+    try_join_all(futures).await
+}
+```
+
+## Error Handling Patterns
+
+```rust
+// Different error types - need common error type
+async fn mixed_operations() -> Result<(A, B), Error> {
+    let (a, b) = try_join!(
+        fetch_a().map_err(Error::from),  // Convert errors
+        fetch_b().map_err(Error::from),
+    )?;
+    Ok((a, b))
+}
+
+// Collect all results, then handle errors
+async fn all_or_nothing(ids: &[u64]) -> Result<Vec<User>> {
+    try_join_all(ids.iter().map(|id| fetch_user(*id))).await
+}
+
+// Collect successes, log failures
+async fn best_effort(ids: &[u64]) -> Vec<User> {
+    let results = futures::future::join_all(
+        ids.iter().map(|id| fetch_user(*id))
+    ).await;
+    
+    results.into_iter()
+        .filter_map(|r| match r {
+            Ok(user) => Some(user),
+            Err(e) => {
+                log::warn!("Failed to fetch user: {}", e);
+                None
+            }
+        })
+        .collect()
+}
+```
+
+## Cancellation Behavior
+
+```rust
+// try_join! cancels remaining futures on error
+async fn with_cancellation() -> Result<()> {
+    // If fetch_a() fails, fetch_b() and fetch_c() are dropped
+    // But "dropped" != "immediately stopped"
+    // They stop at their next .await point
+    
+    try_join!(
+        async {
+            fetch_a().await?;
+            cleanup_a().await;  // May not run if other future fails
+            Ok::<_, Error>(())
+        },
+        async {
+            fetch_b().await?;
+            cleanup_b().await;  // May not run if other future fails
+            Ok::<_, Error>(())
+        },
+    )?;
+    
+    Ok(())
+}
+
+// For guaranteed cleanup, use Drop guards or explicit handling
+```
+
+## With Timeout
+
+```rust
+use tokio::time::{timeout, Duration};
+
+async fn fetch_with_timeout() -> Result<(A, B)> {
+    timeout(
+        Duration::from_secs(10),
+        try_join!(fetch_a(), fetch_b())
+    )
+    .await
+    .map_err(|_| Error::Timeout)?
+}
+
+// Per-operation timeout
+async fn individual_timeouts() -> Result<(A, B)> {
+    try_join!(
+        timeout(Duration::from_secs(5), fetch_a())
+            .map_err(|_| Error::Timeout)
+            .and_then(|r| async { r }),
+        timeout(Duration::from_secs(5), fetch_b())
+            .map_err(|_| Error::Timeout)
+            .and_then(|r| async { r }),
+    )
+}
+```
+
+## try_join! vs FuturesUnordered
+
+```rust
+use futures::stream::{FuturesUnordered, StreamExt};
+
+// try_join!: wait for all, fail fast
+let (a, b, c) = try_join!(fa, fb, fc)?;
+
+// FuturesUnordered: process as they complete
+let mut futures = FuturesUnordered::new();
+futures.push(fetch_a());
+futures.push(fetch_b());
+futures.push(fetch_c());
+
+while let Some(result) = futures.next().await {
+    match result {
+        Ok(data) => process(data),
+        Err(e) => return Err(e),  // Can fail fast manually
+    }
+}
+```
+
+## See Also
+
+- [async-join-parallel](./async-join-parallel.md) - Non-fallible concurrent futures
+- [async-select-racing](./async-select-racing.md) - First-to-complete semantics
+- [err-question-mark](./err-question-mark.md) - Error propagation

package/template/agent/skills/rust-developer/references/rust-rules/async-watch-latest.md

@@ -0,0 +1,189 @@
+# async-watch-latest
+
+> Use `watch` channel for sharing the latest value with multiple observers
+
+## Why It Matters
+
+`watch` is optimized for scenarios where receivers only care about the most recent value, not the history of changes. Unlike `broadcast`, slow receivers don't lag—they simply skip intermediate values. This is perfect for configuration, state, or status that should always reflect the current situation.
+
+## Bad
+
+```rust
+// Using broadcast when only latest value matters
+let (tx, _) = broadcast::channel::<Config>(100);
+
+// Receivers might process stale configs if they're slow
+// And they waste time processing intermediate values
+
+// Using mpsc with buffered stale values
+let (tx, mut rx) = mpsc::channel::<Status>(100);
+// Receiver might process outdated statuses
+```
+
+## Good
+
+```rust
+use tokio::sync::watch;
+
+let (tx, rx) = watch::channel(Config::default());
+
+// Multiple observers
+let rx1 = rx.clone();
+let rx2 = rx.clone();
+
+// Observer 1: waits for changes
+tokio::spawn(async move {
+    let mut rx = rx1;
+    while rx.changed().await.is_ok() {
+        let config = rx.borrow();
+        apply_config(&*config);
+    }
+});
+
+// Observer 2: also sees all changes
+tokio::spawn(async move {
+    let mut rx = rx2;
+    while rx.changed().await.is_ok() {
+        let config = rx.borrow();
+        log_config_change(&*config);
+    }
+});
+
+// Update the value
+tx.send(Config::new())?;
+```
+
+## watch Semantics
+
+```rust
+use tokio::sync::watch;
+
+let (tx, mut rx) = watch::channel("initial");
+
+// Immediate read - no waiting
+assert_eq!(*rx.borrow(), "initial");
+
+// Wait for change
+tx.send("updated")?;
+rx.changed().await?;
+assert_eq!(*rx.borrow(), "updated");
+
+// Multiple rapid updates - receiver sees latest
+tx.send("v1")?;
+tx.send("v2")?;
+tx.send("v3")?;
+rx.changed().await?;
+assert_eq!(*rx.borrow(), "v3");  // Skipped v1, v2
+```
+
+## Configuration Reload Pattern
+
+```rust
+use tokio::sync::watch;
+use std::sync::Arc;
+
+struct AppConfig {
+    log_level: Level,
+    max_connections: usize,
+}
+
+async fn config_watcher(tx: watch::Sender<Arc<AppConfig>>) {
+    loop {
+        tokio::time::sleep(Duration::from_secs(60)).await;
+        
+        if let Ok(new_config) = reload_config_from_disk() {
+            // Only notifies if value actually changed
+            tx.send_if_modified(|current| {
+                if *current != new_config {
+                    *current = Arc::new(new_config);
+                    true
+                } else {
+                    false
+                }
+            });
+        }
+    }
+}
+
+async fn worker(mut config_rx: watch::Receiver<Arc<AppConfig>>) {
+    loop {
+        tokio::select! {
+            _ = config_rx.changed() => {
+                let config = config_rx.borrow().clone();
+                reconfigure(&config);
+            }
+            _ = do_work() => {}
+        }
+    }
+}
+```
+
+## State Machine Updates
+
+```rust
+#[derive(Clone, PartialEq)]
+enum ConnectionState {
+    Disconnected,
+    Connecting,
+    Connected,
+    Error(String),
+}
+
+struct Connection {
+    state_tx: watch::Sender<ConnectionState>,
+    state_rx: watch::Receiver<ConnectionState>,
+}
+
+impl Connection {
+    async fn wait_connected(&mut self) -> Result<(), Error> {
+        loop {
+            let state = self.state_rx.borrow().clone();
+            match state {
+                ConnectionState::Connected => return Ok(()),
+                ConnectionState::Error(e) => return Err(Error::Connection(e)),
+                _ => {
+                    self.state_rx.changed().await?;
+                }
+            }
+        }
+    }
+}
+```
+
+## Borrow vs Clone
+
+```rust
+use tokio::sync::watch;
+
+let (tx, rx) = watch::channel(vec![1, 2, 3]);
+
+// borrow() returns Ref - must not hold across await
+{
+    let data = rx.borrow();
+    println!("{:?}", *data);
+}  // Ref dropped here
+
+// For use across await, clone the data
+let data = rx.borrow().clone();
+some_async_operation().await;
+use_data(&data);  // Safe
+
+// Or use borrow_and_update() to mark as seen
+let data = rx.borrow_and_update().clone();
+```
+
+## watch vs broadcast vs mpsc
+
+| Feature | watch | broadcast | mpsc |
+|---------|-------|-----------|------|
+| Receivers | Multiple | Multiple | Single |
+| Message delivery | Latest only | All messages | All messages |
+| Slow receiver | Skips to latest | Lags/misses | Backpressure |
+| Clone required | No | Yes | No |
+| Best for | Config, status | Events | Work queues |
+
+## See Also
+
+- [async-broadcast-pubsub](./async-broadcast-pubsub.md) - When history matters
+- [async-mpsc-queue](./async-mpsc-queue.md) - Work queue patterns
+- [async-cancellation-token](./async-cancellation-token.md) - Related pattern