javi-forge 1.2.0 → 1.3.0

package/ai-config/skills/systems-iot/rust-systems/SKILL.md

@@ -1,386 +0,0 @@
----
-name: rust-systems
-description: >
-  Rust systems programming patterns for edge computing, Modbus, MQTT, and async runtime.
-  Trigger: Rust, Tokio, Modbus, MQTT, async Rust, edge computing, embedded Rust, systems programming
-tools:
-  - Read
-  - Write
-  - Bash
-  - Grep
-metadata:
-  author: plataforma-industrial
-  version: "2.0"
-  tags: [rust, tokio, modbus, mqtt, async, systems, edge]
-  updated: "2026-02"
----
-
-# Rust Systems Programming
-
-Patterns for building high-performance Rust systems with async runtime.
-
-## Stack
-
-```toml
-[workspace.dependencies]
-tokio = { version = "1.36", features = ["full"] }
-serde = { version = "1.0", features = ["derive"] }
-serde_json = "1.0"
-thiserror = "1.0"
-anyhow = "1.0"
-tracing = "0.1"
-tracing-subscriber = { version = "0.3", features = ["env-filter", "json"] }
-config = "0.14"
-tokio-modbus = "0.13"
-rumqttc = "0.24"
-axum = "0.7"
-uuid = { version = "1.7", features = ["v4", "serde"] }
-chrono = { version = "0.4", features = ["serde"] }
-```
-
-## Project Structure
-
-```
-apps/service/
-├── Cargo.toml
-├── config.yaml
-├── src/
-│   ├── main.rs
-│   ├── lib.rs
-│   ├── config.rs
-│   ├── error.rs
-│   └── domain/
-│       └── mod.rs
-```
-
-## Error Handling
-
-```rust
-use thiserror::Error;
-
-#[derive(Error, Debug)]
-pub enum AppError {
-    #[error("connection failed: {0}")]
-    Connection(#[from] std::io::Error),
-
-    #[error("read failed for {address}: {source}")]
-    Read {
-        address: u16,
-        #[source]
-        source: std::io::Error,
-    },
-
-    #[error("config error: {0}")]
-    Config(#[from] config::ConfigError),
-
-    #[error("serialization error: {0}")]
-    Serialization(#[from] serde_json::Error),
-
-    #[error("not found: {0}")]
-    NotFound(String),
-}
-
-pub type Result<T> = std::result::Result<T, AppError>;
-```
-
-## Configuration
-
-```rust
-use config::{Config, Environment, File};
-use serde::Deserialize;
-use std::path::Path;
-
-#[derive(Debug, Deserialize, Clone)]
-pub struct AppConfig {
-    pub server: ServerConfig,
-    pub mqtt: MqttConfig,
-    pub logging: LoggingConfig,
-}
-
-#[derive(Debug, Deserialize, Clone)]
-pub struct ServerConfig {
-    pub name: String,
-    pub port: u16,
-}
-
-#[derive(Debug, Deserialize, Clone)]
-pub struct MqttConfig {
-    pub host: String,
-    pub port: u16,
-    pub client_id: String,
-    pub topic_prefix: String,
-}
-
-impl AppConfig {
-    pub fn load<P: AsRef<Path>>(path: P) -> Result<Self, config::ConfigError> {
-        Config::builder()
-            .set_default("logging.level", "info")?
-            .add_source(File::from(path.as_ref()))
-            .add_source(
-                Environment::with_prefix("APP")
-                    .separator("__")
-                    .try_parsing(true),
-            )
-            .build()?
-            .try_deserialize()
-    }
-}
-```
-
-## MQTT Publisher
-
-```rust
-use rumqttc::{AsyncClient, EventLoop, MqttOptions, QoS};
-use serde::Serialize;
-use std::time::Duration;
-use tracing::{debug, error, info};
-
-#[derive(Debug, Clone, Serialize)]
-pub struct Message {
-    pub id: uuid::Uuid,
-    pub timestamp: chrono::DateTime<chrono::Utc>,
-    pub value: f64,
-}
-
-pub struct MqttPublisher {
-    client: AsyncClient,
-    topic_prefix: String,
-    qos: QoS,
-}
-
-impl MqttPublisher {
-    pub async fn connect(config: &MqttConfig) -> Result<(Self, EventLoop)> {
-        let mut opts = MqttOptions::new(&config.client_id, &config.host, config.port);
-        opts.set_keep_alive(Duration::from_secs(30))
-            .set_clean_session(true);
-
-        let (client, eventloop) = AsyncClient::new(opts, 100);
-
-        info!(host = %config.host, port = config.port, "MQTT connected");
-
-        Ok((
-            Self {
-                client,
-                topic_prefix: config.topic_prefix.clone(),
-                qos: QoS::AtLeastOnce,
-            },
-            eventloop,
-        ))
-    }
-
-    pub async fn publish(&self, topic: &str, msg: &Message) -> Result<()> {
-        let full_topic = format!("{}/{}", self.topic_prefix, topic);
-        let payload = serde_json::to_vec(msg)?;
-        self.client.publish(&full_topic, self.qos, false, payload).await?;
-        debug!(topic = %full_topic, "Published message");
-        Ok(())
-    }
-}
-
-pub async fn run_eventloop(mut eventloop: EventLoop) {
-    loop {
-        match eventloop.poll().await {
-            Ok(rumqttc::Event::Incoming(rumqttc::Packet::ConnAck(_))) => {
-                info!("MQTT connected");
-            }
-            Ok(_) => {}
-            Err(e) => {
-                error!(error = %e, "MQTT error, reconnecting...");
-                tokio::time::sleep(Duration::from_secs(5)).await;
-            }
-        }
-    }
-}
-```
-
-## Modbus Client
-
-```rust
-use std::sync::Arc;
-use std::time::Duration;
-use tokio::sync::Mutex;
-use tokio::time::timeout;
-use tokio_modbus::prelude::*;
-use tracing::{debug, instrument, warn};
-
-pub struct ModbusClient {
-    context: Arc<Mutex<Box<dyn Reader + Send>>>,
-    timeout_ms: u64,
-    retry_count: u32,
-}
-
-impl ModbusClient {
-    pub async fn connect_tcp(host: &str, port: u16, unit_id: u8) -> Result<Self> {
-        let socket_addr = format!("{}:{}", host, port);
-        let ctx = tcp::connect_slave(socket_addr.parse()?, Slave(unit_id)).await?;
-
-        Ok(Self {
-            context: Arc::new(Mutex::new(Box::new(ctx))),
-            timeout_ms: 5000,
-            retry_count: 3,
-        })
-    }
-
-    #[instrument(skip(self))]
-    pub async fn read_registers(&self, address: u16, count: u16) -> Result<Vec<u16>> {
-        let timeout_duration = Duration::from_millis(self.timeout_ms);
-        let mut last_error = None;
-
-        for attempt in 0..=self.retry_count {
-            if attempt > 0 {
-                debug!(attempt, "Retrying read");
-                tokio::time::sleep(Duration::from_millis(1000)).await;
-            }
-
-            let result = timeout(timeout_duration, async {
-                let mut ctx = self.context.lock().await;
-                ctx.read_holding_registers(address, count).await
-            })
-            .await;
-
-            match result {
-                Ok(Ok(data)) => {
-                    debug!(address, count, "Read {} registers", data.len());
-                    return Ok(data);
-                }
-                Ok(Err(e)) => {
-                    warn!(address, error = %e, attempt, "Read failed");
-                    last_error = Some(AppError::Read { address, source: e.into() });
-                }
-                Err(_) => {
-                    warn!(address, attempt, "Read timed out");
-                    last_error = Some(AppError::Read {
-                        address,
-                        source: std::io::Error::new(std::io::ErrorKind::TimedOut, "timeout").into(),
-                    });
-                }
-            }
-        }
-
-        Err(last_error.unwrap())
-    }
-}
-```
-
-## Axum API
-
-```rust
-use axum::{
-    extract::{Json, State},
-    http::StatusCode,
-    response::IntoResponse,
-    routing::{get, post},
-    Router,
-};
-use serde::{Deserialize, Serialize};
-use std::sync::Arc;
-
-pub struct AppState {
-    pub service: Service,
-}
-
-pub fn create_router(state: Arc<AppState>) -> Router {
-    Router::new()
-        .route("/health", get(health))
-        .route("/api/v1/items", get(list_items).post(create_item))
-        .with_state(state)
-}
-
-async fn health() -> impl IntoResponse {
-    Json(serde_json::json!({ "status": "ok" }))
-}
-
-#[derive(Deserialize)]
-pub struct CreateRequest {
-    pub name: String,
-}
-
-#[derive(Serialize)]
-pub struct ItemResponse {
-    pub id: String,
-    pub name: String,
-}
-
-async fn create_item(
-    State(state): State<Arc<AppState>>,
-    Json(req): Json<CreateRequest>,
-) -> Result<Json<ItemResponse>, AppError> {
-    let item = state.service.create(&req.name).await?;
-    Ok(Json(ItemResponse {
-        id: item.id.to_string(),
-        name: item.name,
-    }))
-}
-
-// Error response
-impl IntoResponse for AppError {
-    fn into_response(self) -> axum::response::Response {
-        let body = Json(serde_json::json!({ "error": self.to_string() }));
-        (StatusCode::INTERNAL_SERVER_ERROR, body).into_response()
-    }
-}
-```
-
-## Main Entry Point
-
-```rust
-use anyhow::Result;
-use std::sync::Arc;
-use tracing::{info, Level};
-use tracing_subscriber::EnvFilter;
-
-mod config;
-mod error;
-mod mqtt;
-mod api;
-
-#[tokio::main]
-async fn main() -> Result<()> {
-    tracing_subscriber::fmt()
-        .with_env_filter(EnvFilter::from_default_env().add_directive(Level::INFO.into()))
-        .json()
-        .init();
-
-    info!("Starting service");
-
-    let config = config::AppConfig::load("config.yaml")?;
-
-    let (mqtt_pub, mqtt_loop) = mqtt::MqttPublisher::connect(&config.mqtt).await?;
-    let mqtt_handle = tokio::spawn(mqtt::run_eventloop(mqtt_loop));
-
-    let state = Arc::new(api::AppState { /* ... */ });
-    let router = api::create_router(state);
-
-    let listener = tokio::net::TcpListener::bind("0.0.0.0:8080").await?;
-    info!("Listening on :8080");
-
-    tokio::select! {
-        _ = tokio::signal::ctrl_c() => {
-            info!("Shutdown signal received");
-        }
-        _ = axum::serve(listener, router) => {}
-        _ = mqtt_handle => {}
-    }
-
-    info!("Shutdown complete");
-    Ok(())
-}
-```
-
-## Conventions
-
-- **Crates:** snake_case (`my_service`)
-- **Modules:** snake_case
-- **Types:** PascalCase
-- **Functions:** snake_case
-- **Constants:** SCREAMING_SNAKE_CASE
-- **Error handling:** `thiserror` for libs, `anyhow` for apps
-- **Async:** Tokio runtime, Arc<Mutex<T>> for shared state
-- **Unsafe:** Forbidden unless absolutely necessary
-
-## Related Skills
-
-- `tokio-async`: Async runtime patterns
-- `mqtt-rumqttc`: IoT messaging
-- `modbus-protocol`: Industrial protocols
-- `websockets`: Real-time communication

package/ai-config/skills/systems-iot/tokio-async/SKILL.md

@@ -1,324 +0,0 @@
----
-name: tokio-async
-description: >
-  Async runtime patterns for Rust with Tokio - spawning, channels, sync primitives.
-  Trigger: tokio, async rust, spawn, channels, mpsc, broadcast, mutex, rwlock
-tools:
-  - Read
-  - Write
-  - Bash
-  - Grep
-metadata:
-  author: plataforma-industrial
-  version: "2.0"
-  tags: [rust, async, concurrency, tokio, runtime]
-  language: rust
-  updated: "2026-02"
----
-
-# Tokio Async Runtime
-
-> Comprehensive async patterns for Rust using Tokio 1.36+
-
-## When to Use
-
-- [ ] Building async Rust applications
-- [ ] Implementing concurrent task processing
-- [ ] Managing channels for inter-task communication
-- [ ] Handling graceful shutdown patterns
-
-## Stack
-
-```toml
-[dependencies]
-tokio = { version = "1.36", features = ["full"] }
-tokio-util = "0.7"
-futures = "0.3"
-async-trait = "0.1"
-tracing = "0.1"
-tracing-subscriber = { version = "0.3", features = ["env-filter"] }
-```
-
-## Critical Patterns
-
-### Pattern 1: Main Entry Point
-
-```rust
-use tracing_subscriber::{layer::SubscriberExt, util::SubscriberInitExt};
-
-#[tokio::main]
-async fn main() -> anyhow::Result<()> {
-    tracing_subscriber::registry()
-        .with(tracing_subscriber::EnvFilter::new(
-            std::env::var("RUST_LOG").unwrap_or_else(|_| "info".into()),
-        ))
-        .with(tracing_subscriber::fmt::layer())
-        .init();
-
-    run().await
-}
-```
-
-### Pattern 2: Async Trait
-
-```rust
-use async_trait::async_trait;
-
-#[async_trait]
-pub trait SensorReader: Send + Sync {
-    async fn read(&self, address: u16) -> Result<f64>;
-    async fn write(&self, address: u16, value: u16) -> Result<()>;
-}
-```
-
-### Pattern 3: Spawn Blocking for CPU Work
-
-```rust
-// ✅ Correct - Move CPU work to blocking pool
-let result = tokio::task::spawn_blocking(move || {
-    heavy_computation(&data)
-}).await?;
-
-// ❌ Incorrect - Blocks the async runtime
-let result = heavy_computation(&data);
-```
-
-## Channels
-
-### mpsc (Multi-producer, Single-consumer)
-
-```rust
-use tokio::sync::mpsc;
-
-#[derive(Debug)]
-enum Command {
-    Read(String),
-    Write(String, f64),
-    Shutdown,
-}
-
-let (tx, mut rx) = mpsc::channel::<Command>(100);
-
-// Producer
-let tx2 = tx.clone();
-tokio::spawn(async move {
-    tx2.send(Command::Read("sensor-1".into())).await.unwrap();
-});
-
-// Consumer
-tokio::spawn(async move {
-    while let Some(cmd) = rx.recv().await {
-        match cmd {
-            Command::Read(id) => { /* handle */ }
-            Command::Write(id, val) => { /* handle */ }
-            Command::Shutdown => break,
-        }
-    }
-});
-```
-
-### broadcast (Multi-producer, Multi-consumer)
-
-```rust
-use tokio::sync::broadcast;
-
-let (tx, _) = broadcast::channel::<Event>(100);
-
-// Multiple subscribers
-let mut rx1 = tx.subscribe();
-let mut rx2 = tx.subscribe();
-
-tokio::spawn(async move {
-    while let Ok(event) = rx1.recv().await {
-        // Handle event
-    }
-});
-
-// Publisher
-tx.send(event).unwrap();
-```
-
-### watch (Latest Value)
-
-```rust
-use tokio::sync::watch;
-
-let (tx, rx) = watch::channel(initial_value);
-
-// Updater
-tx.send_modify(|status| {
-    status.online = true;
-});
-
-// Reader - always gets latest value
-let mut rx2 = rx.clone();
-rx2.changed().await.unwrap();
-let status = rx2.borrow();
-```
-
-## Synchronization
-
-### Mutex & RwLock
-
-```rust
-use std::sync::Arc;
-use tokio::sync::{Mutex, RwLock};
-
-// Mutex for exclusive access
-let cache = Arc::new(Mutex::new(HashMap::new()));
-{
-    let mut guard = cache.lock().await;
-    guard.insert(key, value);
-}
-
-// RwLock for many readers, few writers
-let config = Arc::new(RwLock::new(Config::default()));
-let read_guard = config.read().await;   // Multiple concurrent reads
-let write_guard = config.write().await; // Exclusive write
-```
-
-### Semaphore (Rate Limiting)
-
-```rust
-use tokio::sync::Semaphore;
-
-let semaphore = Arc::new(Semaphore::new(10)); // Max 10 concurrent
-
-for item in items {
-    let permit = semaphore.clone().acquire_owned().await?;
-    tokio::spawn(async move {
-        process(item).await;
-        drop(permit); // Release when done
-    });
-}
-```
-
-## Timers
-
-```rust
-use tokio::time::{sleep, interval, timeout, Duration};
-
-// Sleep
-sleep(Duration::from_secs(5)).await;
-
-// Interval - regular polling
-let mut interval = interval(Duration::from_secs(1));
-loop {
-    interval.tick().await;
-    poll_sensors().await;
-}
-
-// Timeout - fail if too slow
-let result = timeout(Duration::from_secs(5), slow_operation()).await;
-match result {
-    Ok(Ok(value)) => { /* success */ }
-    Ok(Err(e)) => { /* operation error */ }
-    Err(_) => { /* timeout */ }
-}
-```
-
-## Select & Graceful Shutdown
-
-```rust
-use tokio::{select, signal};
-use tokio::sync::broadcast;
-
-async fn run_with_shutdown() -> Result<()> {
-    let (shutdown_tx, _) = broadcast::channel::<()>(1);
-    let mut shutdown_rx = shutdown_tx.subscribe();
-    let mut interval = tokio::time::interval(Duration::from_secs(1));
-
-    loop {
-        select! {
-            _ = interval.tick() => {
-                // Normal work
-                poll_sensors().await;
-            }
-            _ = shutdown_rx.recv() => {
-                tracing::info!("Shutdown signal received");
-                break;
-            }
-            _ = signal::ctrl_c() => {
-                let _ = shutdown_tx.send(());
-                break;
-            }
-        }
-    }
-
-    Ok(())
-}
-```
-
-## JoinSet for Multiple Tasks
-
-```rust
-use tokio::task::JoinSet;
-
-async fn poll_all(sensors: Vec<Config>) -> Vec<Result<Reading>> {
-    let mut set = JoinSet::new();
-
-    for sensor in sensors {
-        set.spawn(async move { read_sensor(&sensor).await });
-    }
-
-    let mut results = Vec::new();
-    while let Some(result) = set.join_next().await {
-        match result {
-            Ok(reading) => results.push(reading),
-            Err(e) => tracing::error!("Task failed: {}", e),
-        }
-    }
-    results
-}
-```
-
-## Anti-Patterns
-
-### Blocking the Runtime
-
-```rust
-// ❌ Never block in async context
-let data = std::fs::read("file.txt")?;
-
-// ✅ Use async I/O or spawn_blocking
-let data = tokio::fs::read("file.txt").await?;
-// Or for sync code:
-let data = tokio::task::spawn_blocking(|| std::fs::read("file.txt")).await??;
-```
-
-### Missing Timeouts on External I/O
-
-```rust
-// ❌ Can hang forever
-let result = client.read().await?;
-
-// ✅ Always timeout external calls
-let result = timeout(Duration::from_secs(5), client.read()).await??;
-```
-
-## Quick Reference
-
-| Task | Pattern |
-|------|---------|
-| Spawn task | `tokio::spawn(async { ... })` |
-| CPU-bound | `spawn_blocking(move \|\| { ... })` |
-| mpsc channel | `mpsc::channel::<T>(100)` |
-| broadcast | `broadcast::channel::<T>(100)` |
-| Mutex | `Mutex::new(data).lock().await` |
-| Semaphore | `Semaphore::new(n).acquire().await` |
-| Timeout | `timeout(Duration::from_secs(5), fut).await` |
-| Interval | `interval(Duration::from_secs(1)).tick().await` |
-| Ctrl+C | `tokio::signal::ctrl_c().await` |
-
-## Resources
-
-- [Tokio Documentation](https://tokio.rs)
-- [Tokio Tutorial](https://tokio.rs/tokio/tutorial)
-- [async-std vs Tokio](https://rust-lang.github.io/async-book/)
-
-## Related Skills
-
-- `rust-systems`: Full Rust patterns
-- `websockets`: Async WebSocket handlers
-- `mqtt-rumqttc`: Async MQTT client
-- `redis-cache`: Async Redis operations