agy-superpowers 5.1.4 → 5.1.5

package/template/agent/skills/rust-developer/references/rust-rules/api-serde-optional.md

@@ -0,0 +1,182 @@
+# api-serde-optional
+
+> Make serde a feature flag, not a hard dependency for library crates
+
+## Why It Matters
+
+Not all users of your library need serialization. Making serde a required dependency adds compile time and binary size for everyone. Feature flags let users opt-in to serde support only when needed, following Rust's philosophy of zero-cost abstractions and minimal dependencies.
+
+## Bad
+
+```rust
+// Cargo.toml
+[dependencies]
+serde = { version = "1.0", features = ["derive"] }
+
+// lib.rs
+use serde::{Serialize, Deserialize};
+
+// Every user pays for serde, even if they don't need it
+#[derive(Serialize, Deserialize)]
+pub struct Config {
+    pub name: String,
+    pub value: i32,
+}
+```
+
+## Good
+
+```rust
+// Cargo.toml
+[dependencies]
+serde = { version = "1.0", features = ["derive"], optional = true }
+
+[features]
+default = []
+serde = ["dep:serde"]
+
+// lib.rs
+#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
+pub struct Config {
+    pub name: String,
+    pub value: i32,
+}
+
+// Users opt-in:
+// my_crate = { version = "1.0", features = ["serde"] }
+```
+
+## Macro Pattern
+
+```rust
+// Reusable macro for serde derives
+#[cfg(feature = "serde")]
+macro_rules! impl_serde {
+    ($($t:ty),*) => {
+        $(
+            impl serde::Serialize for $t {
+                // ...
+            }
+            impl<'de> serde::Deserialize<'de> for $t {
+                // ...
+            }
+        )*
+    };
+}
+
+#[cfg(not(feature = "serde"))]
+macro_rules! impl_serde {
+    ($($t:ty),*) => {};
+}
+
+// Or use cfg_attr for derived impls
+#[derive(Debug, Clone)]
+#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
+pub struct Point {
+    pub x: f64,
+    pub y: f64,
+}
+```
+
+## Feature Documentation
+
+```rust
+// lib.rs
+
+//! # Features
+//!
+//! - `serde`: Enables `Serialize` and `Deserialize` implementations for all types.
+//!
+//! # Example with serde
+//!
+//! ```toml
+//! [dependencies]
+//! my_crate = { version = "1.0", features = ["serde"] }
+//! ```
+
+#![cfg_attr(docsrs, feature(doc_cfg))]
+
+/// A configuration type.
+/// 
+/// When the `serde` feature is enabled, this type implements
+/// `Serialize` and `Deserialize`.
+#[derive(Debug, Clone)]
+#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
+#[cfg_attr(docsrs, doc(cfg(feature = "serde")))]
+pub struct Config {
+    pub name: String,
+}
+```
+
+## Multiple Optional Dependencies
+
+```rust
+// Cargo.toml
+[dependencies]
+serde = { version = "1.0", features = ["derive"], optional = true }
+rkyv = { version = "0.7", optional = true }
+borsh = { version = "0.10", optional = true }
+
+[features]
+default = []
+serde = ["dep:serde"]
+rkyv = ["dep:rkyv"]
+borsh = ["dep:borsh"]
+
+// lib.rs
+#[derive(Debug, Clone)]
+#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
+#[cfg_attr(feature = "rkyv", derive(rkyv::Archive, rkyv::Serialize, rkyv::Deserialize))]
+#[cfg_attr(feature = "borsh", derive(borsh::BorshSerialize, borsh::BorshDeserialize))]
+pub struct Message {
+    pub id: u64,
+    pub content: String,
+}
+```
+
+## Testing with Features
+
+```bash
+# Test without serde
+cargo test
+
+# Test with serde
+cargo test --features serde
+
+# Test all feature combinations
+cargo test --all-features
+```
+
+```rust
+// Test serde round-trip when feature enabled
+#[cfg(feature = "serde")]
+#[test]
+fn test_serde_roundtrip() {
+    let config = Config { name: "test".into() };
+    let json = serde_json::to_string(&config).unwrap();
+    let parsed: Config = serde_json::from_str(&json).unwrap();
+    assert_eq!(config, parsed);
+}
+```
+
+## When to Make Serde Required
+
+```rust
+// ✅ Required: Library is about serialization
+// (e.g., json-schema, config-file parser)
+[dependencies]
+serde = "1.0"
+
+// ✅ Required: Domain heavily uses serde
+// (e.g., API client, data format library)
+
+// ❌ Optional: General-purpose utility library
+// ❌ Optional: Math/algorithm library
+// ❌ Optional: Most libraries!
+```
+
+## See Also
+
+- [proj-lib-main-split](./proj-lib-main-split.md) - Library structure
+- [api-common-traits](./api-common-traits.md) - Core trait implementations
+- [lint-deny-correctness](./lint-deny-correctness.md) - Feature testing

package/template/agent/skills/rust-developer/references/rust-rules/api-typestate.md

@@ -0,0 +1,199 @@
+# api-typestate
+
+> Use typestate pattern to encode state machine invariants in the type system
+
+## Why It Matters
+
+State machines with runtime state checks ("are we connected?", "is the transaction started?") can have invalid transitions. The typestate pattern uses different types for each state, making invalid state transitions compile errors. The compiler enforces your state machine.
+
+## Bad
+
+```rust
+struct Connection {
+    state: ConnectionState,
+    socket: Option<TcpStream>,
+}
+
+enum ConnectionState {
+    Disconnected,
+    Connected,
+    Authenticated,
+}
+
+impl Connection {
+    fn send(&mut self, data: &[u8]) -> Result<(), Error> {
+        // Runtime check - can fail if called in wrong state
+        if self.state != ConnectionState::Authenticated {
+            return Err(Error::NotAuthenticated);
+        }
+        self.socket.as_mut().unwrap().write_all(data)?;
+        Ok(())
+    }
+    
+    fn authenticate(&mut self, password: &str) -> Result<(), Error> {
+        // Runtime check - can fail
+        if self.state != ConnectionState::Connected {
+            return Err(Error::NotConnected);
+        }
+        // ...
+    }
+}
+
+// Bug: forgot to authenticate
+let mut conn = Connection::new();
+conn.connect()?;
+conn.send(b"data")?;  // Runtime error: NotAuthenticated
+```
+
+## Good
+
+```rust
+// Different types for each state
+struct Disconnected;
+struct Connected { socket: TcpStream }
+struct Authenticated { socket: TcpStream, session: Session }
+
+struct Connection<State> {
+    state: State,
+}
+
+impl Connection<Disconnected> {
+    fn new() -> Self {
+        Connection { state: Disconnected }
+    }
+    
+    fn connect(self, addr: &str) -> Result<Connection<Connected>, Error> {
+        let socket = TcpStream::connect(addr)?;
+        Ok(Connection { state: Connected { socket } })
+    }
+}
+
+impl Connection<Connected> {
+    fn authenticate(self, password: &str) -> Result<Connection<Authenticated>, Error> {
+        let session = do_auth(&self.state.socket, password)?;
+        Ok(Connection {
+            state: Authenticated { socket: self.state.socket, session }
+        })
+    }
+}
+
+impl Connection<Authenticated> {
+    fn send(&mut self, data: &[u8]) -> Result<(), Error> {
+        // No runtime check needed - type guarantees we're authenticated
+        self.state.socket.write_all(data)?;
+        Ok(())
+    }
+}
+
+// Bug: forgot to authenticate
+let conn = Connection::new();
+let conn = conn.connect("server:8080")?;
+conn.send(b"data");  // Compile error! send() not available on Connection<Connected>
+
+// Correct usage
+let conn = Connection::new();
+let conn = conn.connect("server:8080")?;
+let mut conn = conn.authenticate("secret")?;
+conn.send(b"data")?;  // Works - type is Connection<Authenticated>
+```
+
+## Builder Typestate
+
+```rust
+// Enforce required fields via typestate
+struct BuilderNoUrl;
+struct BuilderWithUrl { url: String }
+
+struct RequestBuilder<State> {
+    state: State,
+    timeout: Option<Duration>,
+}
+
+impl RequestBuilder<BuilderNoUrl> {
+    fn new() -> Self {
+        RequestBuilder {
+            state: BuilderNoUrl,
+            timeout: None,
+        }
+    }
+    
+    fn url(self, url: &str) -> RequestBuilder<BuilderWithUrl> {
+        RequestBuilder {
+            state: BuilderWithUrl { url: url.to_string() },
+            timeout: self.timeout,
+        }
+    }
+}
+
+impl RequestBuilder<BuilderWithUrl> {
+    fn timeout(mut self, t: Duration) -> Self {
+        self.timeout = Some(t);
+        self
+    }
+    
+    // Only available once URL is set
+    fn build(self) -> Request {
+        Request {
+            url: self.state.url,
+            timeout: self.timeout,
+        }
+    }
+}
+
+// Compile error: build() not available
+let bad = RequestBuilder::new().build();
+
+// Correct: must set URL first
+let good = RequestBuilder::new()
+    .url("https://example.com")
+    .timeout(Duration::from_secs(30))
+    .build();
+```
+
+## Transaction Example
+
+```rust
+struct NotStarted;
+struct InProgress { tx_id: u64 }
+struct Committed;
+
+struct Transaction<State> {
+    conn: Connection,
+    state: State,
+}
+
+impl Transaction<NotStarted> {
+    fn begin(conn: Connection) -> Result<Transaction<InProgress>, Error> {
+        let tx_id = conn.execute("BEGIN")?;
+        Ok(Transaction {
+            conn,
+            state: InProgress { tx_id },
+        })
+    }
+}
+
+impl Transaction<InProgress> {
+    fn execute(&mut self, sql: &str) -> Result<(), Error> {
+        self.conn.execute(sql)
+    }
+    
+    fn commit(self) -> Result<Transaction<Committed>, Error> {
+        self.conn.execute("COMMIT")?;
+        Ok(Transaction {
+            conn: self.conn,
+            state: Committed,
+        })
+    }
+    
+    fn rollback(self) -> Connection {
+        let _ = self.conn.execute("ROLLBACK");
+        self.conn
+    }
+}
+```
+
+## See Also
+
+- [api-builder-pattern](./api-builder-pattern.md) - Basic builder pattern
+- [api-parse-dont-validate](./api-parse-dont-validate.md) - Type-driven invariants
+- [api-sealed-trait](./api-sealed-trait.md) - Restricting trait implementations

package/template/agent/skills/rust-developer/references/rust-rules/async-bounded-channel.md

@@ -0,0 +1,175 @@
+# async-bounded-channel
+
+> Use bounded channels to apply backpressure and prevent unbounded memory growth
+
+## Why It Matters
+
+Unbounded channels grow without limit when producers outpace consumers. In production, this leads to memory exhaustion. Bounded channels apply backpressure—producers wait when the channel is full, naturally throttling the system. This prevents OOM and makes resource usage predictable.
+
+## Bad
+
+```rust
+use tokio::sync::mpsc;
+
+// Unbounded channel - can grow forever
+let (tx, mut rx) = mpsc::unbounded_channel::<Message>();
+
+// Fast producer, slow consumer = unbounded memory growth
+tokio::spawn(async move {
+    loop {
+        let msg = generate_message();
+        tx.send(msg).unwrap();  // Never blocks, never fails (until OOM)
+    }
+});
+
+tokio::spawn(async move {
+    while let Some(msg) = rx.recv().await {
+        slow_process(msg).await;  // Can't keep up
+    }
+});
+// Memory grows unboundedly until crash
+```
+
+## Good
+
+```rust
+use tokio::sync::mpsc;
+
+// Bounded channel - backpressure when full
+let (tx, mut rx) = mpsc::channel::<Message>(100);  // Max 100 items
+
+// Producer waits when channel full
+tokio::spawn(async move {
+    loop {
+        let msg = generate_message();
+        // Blocks if channel is full - natural backpressure
+        tx.send(msg).await.unwrap();
+    }
+});
+
+tokio::spawn(async move {
+    while let Some(msg) = rx.recv().await {
+        slow_process(msg).await;
+    }
+});
+// Memory usage capped at ~100 messages
+```
+
+## Choosing Buffer Size
+
+```rust
+// Too small: frequent blocking, reduced throughput
+let (tx, rx) = mpsc::channel::<Item>(1);
+
+// Too large: delayed backpressure, memory waste
+let (tx, rx) = mpsc::channel::<Item>(1_000_000);
+
+// Guidelines:
+// - Start with expected burst size
+// - Measure actual usage in production
+// - Err on the smaller side initially
+
+// Small items, high throughput
+let (tx, rx) = mpsc::channel::<u64>(1000);
+
+// Large items, moderate throughput  
+let (tx, rx) = mpsc::channel::<LargeStruct>(100);
+
+// Low latency requirement
+let (tx, rx) = mpsc::channel::<Command>(10);
+```
+
+## Handling Full Channel
+
+```rust
+use tokio::sync::mpsc;
+use tokio::time::{timeout, Duration};
+
+let (tx, mut rx) = mpsc::channel::<Message>(100);
+
+// Option 1: Wait indefinitely (default)
+tx.send(msg).await?;
+
+// Option 2: Try send, fail if full
+match tx.try_send(msg) {
+    Ok(()) => println!("Sent"),
+    Err(TrySendError::Full(msg)) => {
+        println!("Channel full, dropping message");
+    }
+    Err(TrySendError::Closed(msg)) => {
+        println!("Receiver dropped");
+    }
+}
+
+// Option 3: Timeout
+match timeout(Duration::from_secs(1), tx.send(msg)).await {
+    Ok(Ok(())) => println!("Sent"),
+    Ok(Err(_)) => println!("Channel closed"),
+    Err(_) => println!("Timeout - channel full for too long"),
+}
+
+// Option 4: send with permit reservation
+let permit = tx.reserve().await?;
+permit.send(msg);  // Guaranteed to succeed
+```
+
+## Channel Types
+
+```rust
+// mpsc: many producers, single consumer
+let (tx, rx) = mpsc::channel::<Message>(100);
+let tx2 = tx.clone();  // Can clone sender
+
+// oneshot: single value, one producer, one consumer
+let (tx, rx) = oneshot::channel::<Response>();
+tx.send(response);  // Can only send once
+
+// broadcast: multiple consumers, each gets all messages
+let (tx, _) = broadcast::channel::<Event>(100);
+let mut rx1 = tx.subscribe();
+let mut rx2 = tx.subscribe();
+
+// watch: single latest value, multiple consumers
+let (tx, rx) = watch::channel::<State>(initial);
+// Receivers see latest value, not all values
+```
+
+## Worker Pool Pattern
+
+```rust
+async fn process_with_workers(items: Vec<Item>) -> Vec<Result> {
+    let (tx, rx) = mpsc::channel(100);
+    let rx = Arc::new(Mutex::new(rx));
+    
+    // Spawn worker pool
+    let workers: Vec<_> = (0..4).map(|_| {
+        let rx = rx.clone();
+        tokio::spawn(async move {
+            loop {
+                let item = {
+                    let mut rx = rx.lock().await;
+                    rx.recv().await
+                };
+                match item {
+                    Some(item) => process(item).await,
+                    None => break,
+                }
+            }
+        })
+    }).collect();
+    
+    // Send items
+    for item in items {
+        tx.send(item).await.unwrap();
+    }
+    drop(tx);  // Signal workers to stop
+    
+    futures::future::join_all(workers).await;
+}
+```
+
+## See Also
+
+- [async-mpsc-queue](./async-mpsc-queue.md) - Multi-producer patterns
+- [async-oneshot-response](./async-oneshot-response.md) - Request-response pattern
+- [async-watch-latest](./async-watch-latest.md) - Latest-value broadcasting