@heyai-rules/pilo-masterkit 2.1.0 → 3.1.0

package/.agent/rules/rust/hooks.md

@@ -1,16 +1,16 @@
----
-paths:
-  - "**/*.rs"
-  - "**/Cargo.toml"
----
-# Rust Hooks
-
-> This file extends [common/hooks.md](../common/hooks.md) with Rust-specific content.
-
-## PostToolUse Hooks
-
-Configure in `~/.claude/settings.json`:
-
-- **cargo fmt**: Auto-format `.rs` files after edit
-- **cargo clippy**: Run lint checks after editing Rust files
-- **cargo check**: Verify compilation after changes (faster than `cargo build`)
+---
+paths:
+  - "**/*.rs"
+  - "**/Cargo.toml"
+---
+# Rust Hooks
+
+> This file extends [common/hooks.md](../common/hooks.md) with Rust-specific content.
+
+## PostToolUse Hooks
+
+Configure in `~/.claude/settings.json`:
+
+- **cargo fmt**: Auto-format `.rs` files after edit
+- **cargo clippy**: Run lint checks after editing Rust files
+- **cargo check**: Verify compilation after changes (faster than `cargo build`)

package/.agent/rules/rust/patterns.md

@@ -1,168 +1,168 @@
----
-paths:
-  - "**/*.rs"
----
-# Rust Patterns
-
-> This file extends [common/patterns.md](../common/patterns.md) with Rust-specific content.
-
-## Repository Pattern with Traits
-
-Encapsulate data access behind a trait:
-
-```rust
-pub trait OrderRepository: Send + Sync {
-    fn find_by_id(&self, id: u64) -> Result<Option<Order>, StorageError>;
-    fn find_all(&self) -> Result<Vec<Order>, StorageError>;
-    fn save(&self, order: &Order) -> Result<Order, StorageError>;
-    fn delete(&self, id: u64) -> Result<(), StorageError>;
-}
-```
-
-Concrete implementations handle storage details (Postgres, SQLite, in-memory for tests).
-
-## Service Layer
-
-Business logic in service structs; inject dependencies via constructor:
-
-```rust
-pub struct OrderService {
-    repo: Box<dyn OrderRepository>,
-    payment: Box<dyn PaymentGateway>,
-}
-
-impl OrderService {
-    pub fn new(repo: Box<dyn OrderRepository>, payment: Box<dyn PaymentGateway>) -> Self {
-        Self { repo, payment }
-    }
-
-    pub fn place_order(&self, request: CreateOrderRequest) -> anyhow::Result<OrderSummary> {
-        let order = Order::from(request);
-        self.payment.charge(order.total())?;
-        let saved = self.repo.save(&order)?;
-        Ok(OrderSummary::from(saved))
-    }
-}
-```
-
-## Newtype Pattern for Type Safety
-
-Prevent argument mix-ups with distinct wrapper types:
-
-```rust
-struct UserId(u64);
-struct OrderId(u64);
-
-fn get_order(user: UserId, order: OrderId) -> anyhow::Result<Order> {
-    // Can't accidentally swap user and order IDs at call sites
-    todo!()
-}
-```
-
-## Enum State Machines
-
-Model states as enums — make illegal states unrepresentable:
-
-```rust
-enum ConnectionState {
-    Disconnected,
-    Connecting { attempt: u32 },
-    Connected { session_id: String },
-    Failed { reason: String, retries: u32 },
-}
-
-fn handle(state: &ConnectionState) {
-    match state {
-        ConnectionState::Disconnected => connect(),
-        ConnectionState::Connecting { attempt } if *attempt > 3 => abort(),
-        ConnectionState::Connecting { .. } => wait(),
-        ConnectionState::Connected { session_id } => use_session(session_id),
-        ConnectionState::Failed { retries, .. } if *retries < 5 => retry(),
-        ConnectionState::Failed { reason, .. } => log_failure(reason),
-    }
-}
-```
-
-Always match exhaustively — no wildcard `_` for business-critical enums.
-
-## Builder Pattern
-
-Use for structs with many optional parameters:
-
-```rust
-pub struct ServerConfig {
-    host: String,
-    port: u16,
-    max_connections: usize,
-}
-
-impl ServerConfig {
-    pub fn builder(host: impl Into<String>, port: u16) -> ServerConfigBuilder {
-        ServerConfigBuilder {
-            host: host.into(),
-            port,
-            max_connections: 100,
-        }
-    }
-}
-
-pub struct ServerConfigBuilder {
-    host: String,
-    port: u16,
-    max_connections: usize,
-}
-
-impl ServerConfigBuilder {
-    pub fn max_connections(mut self, n: usize) -> Self {
-        self.max_connections = n;
-        self
-    }
-
-    pub fn build(self) -> ServerConfig {
-        ServerConfig {
-            host: self.host,
-            port: self.port,
-            max_connections: self.max_connections,
-        }
-    }
-}
-```
-
-## Sealed Traits for Extensibility Control
-
-Use a private module to seal a trait, preventing external implementations:
-
-```rust
-mod private {
-    pub trait Sealed {}
-}
-
-pub trait Format: private::Sealed {
-    fn encode(&self, data: &[u8]) -> Vec<u8>;
-}
-
-pub struct Json;
-impl private::Sealed for Json {}
-impl Format for Json {
-    fn encode(&self, data: &[u8]) -> Vec<u8> { todo!() }
-}
-```
-
-## API Response Envelope
-
-Consistent API responses using a generic enum:
-
-```rust
-#[derive(Debug, serde::Serialize)]
-#[serde(tag = "status")]
-pub enum ApiResponse<T: serde::Serialize> {
-    #[serde(rename = "ok")]
-    Ok { data: T },
-    #[serde(rename = "error")]
-    Error { message: String },
-}
-```
-
-## References
-
-See skill: `rust-patterns` for comprehensive patterns including ownership, traits, generics, concurrency, and async.
+---
+paths:
+  - "**/*.rs"
+---
+# Rust Patterns
+
+> This file extends [common/patterns.md](../common/patterns.md) with Rust-specific content.
+
+## Repository Pattern with Traits
+
+Encapsulate data access behind a trait:
+
+```rust
+pub trait OrderRepository: Send + Sync {
+    fn find_by_id(&self, id: u64) -> Result<Option<Order>, StorageError>;
+    fn find_all(&self) -> Result<Vec<Order>, StorageError>;
+    fn save(&self, order: &Order) -> Result<Order, StorageError>;
+    fn delete(&self, id: u64) -> Result<(), StorageError>;
+}
+```
+
+Concrete implementations handle storage details (Postgres, SQLite, in-memory for tests).
+
+## Service Layer
+
+Business logic in service structs; inject dependencies via constructor:
+
+```rust
+pub struct OrderService {
+    repo: Box<dyn OrderRepository>,
+    payment: Box<dyn PaymentGateway>,
+}
+
+impl OrderService {
+    pub fn new(repo: Box<dyn OrderRepository>, payment: Box<dyn PaymentGateway>) -> Self {
+        Self { repo, payment }
+    }
+
+    pub fn place_order(&self, request: CreateOrderRequest) -> anyhow::Result<OrderSummary> {
+        let order = Order::from(request);
+        self.payment.charge(order.total())?;
+        let saved = self.repo.save(&order)?;
+        Ok(OrderSummary::from(saved))
+    }
+}
+```
+
+## Newtype Pattern for Type Safety
+
+Prevent argument mix-ups with distinct wrapper types:
+
+```rust
+struct UserId(u64);
+struct OrderId(u64);
+
+fn get_order(user: UserId, order: OrderId) -> anyhow::Result<Order> {
+    // Can't accidentally swap user and order IDs at call sites
+    todo!()
+}
+```
+
+## Enum State Machines
+
+Model states as enums — make illegal states unrepresentable:
+
+```rust
+enum ConnectionState {
+    Disconnected,
+    Connecting { attempt: u32 },
+    Connected { session_id: String },
+    Failed { reason: String, retries: u32 },
+}
+
+fn handle(state: &ConnectionState) {
+    match state {
+        ConnectionState::Disconnected => connect(),
+        ConnectionState::Connecting { attempt } if *attempt > 3 => abort(),
+        ConnectionState::Connecting { .. } => wait(),
+        ConnectionState::Connected { session_id } => use_session(session_id),
+        ConnectionState::Failed { retries, .. } if *retries < 5 => retry(),
+        ConnectionState::Failed { reason, .. } => log_failure(reason),
+    }
+}
+```
+
+Always match exhaustively — no wildcard `_` for business-critical enums.
+
+## Builder Pattern
+
+Use for structs with many optional parameters:
+
+```rust
+pub struct ServerConfig {
+    host: String,
+    port: u16,
+    max_connections: usize,
+}
+
+impl ServerConfig {
+    pub fn builder(host: impl Into<String>, port: u16) -> ServerConfigBuilder {
+        ServerConfigBuilder {
+            host: host.into(),
+            port,
+            max_connections: 100,
+        }
+    }
+}
+
+pub struct ServerConfigBuilder {
+    host: String,
+    port: u16,
+    max_connections: usize,
+}
+
+impl ServerConfigBuilder {
+    pub fn max_connections(mut self, n: usize) -> Self {
+        self.max_connections = n;
+        self
+    }
+
+    pub fn build(self) -> ServerConfig {
+        ServerConfig {
+            host: self.host,
+            port: self.port,
+            max_connections: self.max_connections,
+        }
+    }
+}
+```
+
+## Sealed Traits for Extensibility Control
+
+Use a private module to seal a trait, preventing external implementations:
+
+```rust
+mod private {
+    pub trait Sealed {}
+}
+
+pub trait Format: private::Sealed {
+    fn encode(&self, data: &[u8]) -> Vec<u8>;
+}
+
+pub struct Json;
+impl private::Sealed for Json {}
+impl Format for Json {
+    fn encode(&self, data: &[u8]) -> Vec<u8> { todo!() }
+}
+```
+
+## API Response Envelope
+
+Consistent API responses using a generic enum:
+
+```rust
+#[derive(Debug, serde::Serialize)]
+#[serde(tag = "status")]
+pub enum ApiResponse<T: serde::Serialize> {
+    #[serde(rename = "ok")]
+    Ok { data: T },
+    #[serde(rename = "error")]
+    Error { message: String },
+}
+```
+
+## References
+
+See skill: `rust-patterns` for comprehensive patterns including ownership, traits, generics, concurrency, and async.

package/.agent/rules/rust/security.md

@@ -1,141 +1,141 @@
----
-paths:
-  - "**/*.rs"
----
-# Rust Security
-
-> This file extends [common/security.md](../common/security.md) with Rust-specific content.
-
-## Secrets Management
-
-- Never hardcode API keys, tokens, or credentials in source code
-- Use environment variables: `std::env::var("API_KEY")`
-- Fail fast if required secrets are missing at startup
-- Keep `.env` files in `.gitignore`
-
-```rust
-// BAD
-const API_KEY: &str = "sk-abc123...";
-
-// GOOD — environment variable with early validation
-fn load_api_key() -> anyhow::Result<String> {
-    std::env::var("PAYMENT_API_KEY")
-        .context("PAYMENT_API_KEY must be set")
-}
-```
-
-## SQL Injection Prevention
-
-- Always use parameterized queries — never format user input into SQL strings
-- Use query builder or ORM (sqlx, diesel, sea-orm) with bind parameters
-
-```rust
-// BAD — SQL injection via format string
-let query = format!("SELECT * FROM users WHERE name = '{name}'");
-sqlx::query(&query).fetch_one(&pool).await?;
-
-// GOOD — parameterized query with sqlx
-// Placeholder syntax varies by backend: Postgres: $1  |  MySQL: ?  |  SQLite: $1
-sqlx::query("SELECT * FROM users WHERE name = $1")
-    .bind(&name)
-    .fetch_one(&pool)
-    .await?;
-```
-
-## Input Validation
-
-- Validate all user input at system boundaries before processing
-- Use the type system to enforce invariants (newtype pattern)
-- Parse, don't validate — convert unstructured data to typed structs at the boundary
-- Reject invalid input with clear error messages
-
-```rust
-// Parse, don't validate — invalid states are unrepresentable
-pub struct Email(String);
-
-impl Email {
-    pub fn parse(input: &str) -> Result<Self, ValidationError> {
-        let trimmed = input.trim();
-        let at_pos = trimmed.find('@')
-            .filter(|&p| p > 0 && p < trimmed.len() - 1)
-            .ok_or_else(|| ValidationError::InvalidEmail(input.to_string()))?;
-        let domain = &trimmed[at_pos + 1..];
-        if trimmed.len() > 254 || !domain.contains('.') {
-            return Err(ValidationError::InvalidEmail(input.to_string()));
-        }
-        // For production use, prefer a validated email crate (e.g., `email_address`)
-        Ok(Self(trimmed.to_string()))
-    }
-
-    pub fn as_str(&self) -> &str {
-        &self.0
-    }
-}
-```
-
-## Unsafe Code
-
-- Minimize `unsafe` blocks — prefer safe abstractions
-- Every `unsafe` block must have a `// SAFETY:` comment explaining the invariant
-- Never use `unsafe` to bypass the borrow checker for convenience
-- Audit all `unsafe` code during review — it is a red flag without justification
-- Prefer `safe` FFI wrappers around C libraries
-
-```rust
-// GOOD — safety comment documents ALL required invariants
-let widget: &Widget = {
-    // SAFETY: `ptr` is non-null, aligned, points to an initialized Widget,
-    // and no mutable references or mutations exist for its lifetime.
-    unsafe { &*ptr }
-};
-
-// BAD — no safety justification
-unsafe { &*ptr }
-```
-
-## Dependency Security
-
-- Run `cargo audit` to scan for known CVEs in dependencies
-- Run `cargo deny check` for license and advisory compliance
-- Use `cargo tree` to audit transitive dependencies
-- Keep dependencies updated — set up Dependabot or Renovate
-- Minimize dependency count — evaluate before adding new crates
-
-```bash
-# Security audit
-cargo audit
-
-# Deny advisories, duplicate versions, and restricted licenses
-cargo deny check
-
-# Inspect dependency tree
-cargo tree
-cargo tree -d  # Show duplicates only
-```
-
-## Error Messages
-
-- Never expose internal paths, stack traces, or database errors in API responses
-- Log detailed errors server-side; return generic messages to clients
-- Use `tracing` or `log` for structured server-side logging
-
-```rust
-// Map errors to appropriate status codes and generic messages
-// (Example uses axum; adapt the response type to your framework)
-match order_service.find_by_id(id) {
-    Ok(order) => Ok((StatusCode::OK, Json(order))),
-    Err(ServiceError::NotFound(_)) => {
-        tracing::info!(order_id = id, "order not found");
-        Err((StatusCode::NOT_FOUND, "Resource not found"))
-    }
-    Err(e) => {
-        tracing::error!(order_id = id, error = %e, "unexpected error");
-        Err((StatusCode::INTERNAL_SERVER_ERROR, "Internal server error"))
-    }
-}
-```
-
-## References
-
-See skill: `rust-patterns` for unsafe code guidelines and ownership patterns.
-See skill: `security-review` for general security checklists.
+---
+paths:
+  - "**/*.rs"
+---
+# Rust Security
+
+> This file extends [common/security.md](../common/security.md) with Rust-specific content.
+
+## Secrets Management
+
+- Never hardcode API keys, tokens, or credentials in source code
+- Use environment variables: `std::env::var("API_KEY")`
+- Fail fast if required secrets are missing at startup
+- Keep `.env` files in `.gitignore`
+
+```rust
+// BAD
+const API_KEY: &str = "sk-abc123...";
+
+// GOOD — environment variable with early validation
+fn load_api_key() -> anyhow::Result<String> {
+    std::env::var("PAYMENT_API_KEY")
+        .context("PAYMENT_API_KEY must be set")
+}
+```
+
+## SQL Injection Prevention
+
+- Always use parameterized queries — never format user input into SQL strings
+- Use query builder or ORM (sqlx, diesel, sea-orm) with bind parameters
+
+```rust
+// BAD — SQL injection via format string
+let query = format!("SELECT * FROM users WHERE name = '{name}'");
+sqlx::query(&query).fetch_one(&pool).await?;
+
+// GOOD — parameterized query with sqlx
+// Placeholder syntax varies by backend: Postgres: $1  |  MySQL: ?  |  SQLite: $1
+sqlx::query("SELECT * FROM users WHERE name = $1")
+    .bind(&name)
+    .fetch_one(&pool)
+    .await?;
+```
+
+## Input Validation
+
+- Validate all user input at system boundaries before processing
+- Use the type system to enforce invariants (newtype pattern)
+- Parse, don't validate — convert unstructured data to typed structs at the boundary
+- Reject invalid input with clear error messages
+
+```rust
+// Parse, don't validate — invalid states are unrepresentable
+pub struct Email(String);
+
+impl Email {
+    pub fn parse(input: &str) -> Result<Self, ValidationError> {
+        let trimmed = input.trim();
+        let at_pos = trimmed.find('@')
+            .filter(|&p| p > 0 && p < trimmed.len() - 1)
+            .ok_or_else(|| ValidationError::InvalidEmail(input.to_string()))?;
+        let domain = &trimmed[at_pos + 1..];
+        if trimmed.len() > 254 || !domain.contains('.') {
+            return Err(ValidationError::InvalidEmail(input.to_string()));
+        }
+        // For production use, prefer a validated email crate (e.g., `email_address`)
+        Ok(Self(trimmed.to_string()))
+    }
+
+    pub fn as_str(&self) -> &str {
+        &self.0
+    }
+}
+```
+
+## Unsafe Code
+
+- Minimize `unsafe` blocks — prefer safe abstractions
+- Every `unsafe` block must have a `// SAFETY:` comment explaining the invariant
+- Never use `unsafe` to bypass the borrow checker for convenience
+- Audit all `unsafe` code during review — it is a red flag without justification
+- Prefer `safe` FFI wrappers around C libraries
+
+```rust
+// GOOD — safety comment documents ALL required invariants
+let widget: &Widget = {
+    // SAFETY: `ptr` is non-null, aligned, points to an initialized Widget,
+    // and no mutable references or mutations exist for its lifetime.
+    unsafe { &*ptr }
+};
+
+// BAD — no safety justification
+unsafe { &*ptr }
+```
+
+## Dependency Security
+
+- Run `cargo audit` to scan for known CVEs in dependencies
+- Run `cargo deny check` for license and advisory compliance
+- Use `cargo tree` to audit transitive dependencies
+- Keep dependencies updated — set up Dependabot or Renovate
+- Minimize dependency count — evaluate before adding new crates
+
+```bash
+# Security audit
+cargo audit
+
+# Deny advisories, duplicate versions, and restricted licenses
+cargo deny check
+
+# Inspect dependency tree
+cargo tree
+cargo tree -d  # Show duplicates only
+```
+
+## Error Messages
+
+- Never expose internal paths, stack traces, or database errors in API responses
+- Log detailed errors server-side; return generic messages to clients
+- Use `tracing` or `log` for structured server-side logging
+
+```rust
+// Map errors to appropriate status codes and generic messages
+// (Example uses axum; adapt the response type to your framework)
+match order_service.find_by_id(id) {
+    Ok(order) => Ok((StatusCode::OK, Json(order))),
+    Err(ServiceError::NotFound(_)) => {
+        tracing::info!(order_id = id, "order not found");
+        Err((StatusCode::NOT_FOUND, "Resource not found"))
+    }
+    Err(e) => {
+        tracing::error!(order_id = id, error = %e, "unexpected error");
+        Err((StatusCode::INTERNAL_SERVER_ERROR, "Internal server error"))
+    }
+}
+```
+
+## References
+
+See skill: `rust-patterns` for unsafe code guidelines and ownership patterns.
+See skill: `security-review` for general security checklists.