claude-plugins/acidaos/skills/rust-dev/SKILL.md

---
name: rust-dev
description: Desenvolvimento do AcidaOS Core em Rust — criar crates, definir endpoints Axum, debugar erros do compilador. Usar quando "rust", "axum", "cargo", "crate", "core", "acidaos core", "rust error", "borrow checker", desenvolvimento do motor central do AcidaOS.
allowed-tools: Read, Write, Edit, Bash, mcp__memory-supabase__search_memories, mcp__gitea__get_file_content, mcp__gitea__create_file, mcp__gitea__update_file
---

# AcidaOS Rust Dev

Skill para desenvolvimento do **Core do AcidaOS** em Rust.

## Contexto do Projecto

```
acidaos-core (Rust)
├── src/
│   ├── api/          ← endpoints Axum (REST/gRPC)
│   ├── kernel/       ← Agent Kernel & Scheduler
│   ├── security/     ← Sandboxing, isolamento WASM
│   ├── memory/       ← Context & Memory Engine
│   ├── registry/     ← Parsers de skills/plugins
│   ├── observability/← Logging, tracing
│   └── ethics/       ← Constitution Engine
├── crates/           ← bibliotecas internas
└── Cargo.toml
```

**Stack:** Rust stable | Axum | Tokio | Serde | Tracing | SQLx | wasmtime

## Protocolo Inicial

```
mcp__memory-supabase__search_memories "acidaos core [componente]"
mcp__gitea__get_file_content acidaos-core/Cargo.toml  # verificar dependências actuais
```

---

## Operações

### 1. Criar novo crate (`/rust-create-crate`)

**Input:** Nome do crate e propósito

**Passos:**
1. Criar directório `crates/<nome>/`
2. Gerar `Cargo.toml` com dependências mínimas
3. Criar `src/lib.rs` com estrutura base
4. Adicionar ao workspace `Cargo.toml`
5. Criar `src/error.rs` com tipo de erro custom usando `thiserror`

**Template `Cargo.toml`:**
```toml
[package]
name = "acidaos-<nome>"
version = "0.1.0"
edition = "2021"
description = "<descrição>"

[dependencies]
tracing = "0.1"
serde = { version = "1", features = ["derive"] }
thiserror = "1"
tokio = { version = "1", features = ["full"] }
```

**Template `src/lib.rs`:**
```rust
//! # acidaos-<nome>
//!
//! <Descrição do módulo>
//!
//! ## Exemplo
//! ```rust
//! use acidaos_<nome>::<TipoPrincipal>;
//! ```

mod error;
pub use error::Error;

pub type Result<T> = std::result::Result<T, Error>;
```

**Template `src/error.rs`:**
```rust
use thiserror::Error;

#[derive(Debug, Error)]
pub enum Error {
    #[error("Erro de inicialização: {0}")]
    Init(String),

    #[error("Operação não suportada: {0}")]
    Unsupported(String),
}
```

---

### 2. Definir endpoint Axum (`/rust-define-api-endpoint`)

**Input:** Definição do endpoint (método, path, request/response types) de uma SPEC.md

**Template de endpoint:**
```rust
use axum::{
    extract::{Path, State},
    http::StatusCode,
    response::Json,
    routing::{get, post},
    Router,
};
use serde::{Deserialize, Serialize};
use tracing::instrument;

// --- Tipos ---

#[derive(Debug, Deserialize)]
pub struct <NomeRequest> {
    // campos do request
}

#[derive(Debug, Serialize)]
pub struct <NomeResponse> {
    // campos do response
}

// --- Handler ---

#[instrument(skip(state))]
pub async fn <nome_handler>(
    State(state): State<AppState>,
    Json(req): Json<<NomeRequest>>,
) -> Result<Json<<NomeResponse>>, StatusCode> {
    tracing::info!("Processando <nome>");

    // lógica do handler

    Ok(Json(<NomeResponse> {
        // preencher response
    }))
}

// --- Router ---

pub fn <nome>_router() -> Router<AppState> {
    Router::new()
        .route("/<path>", post(<nome_handler>))
}
```

**Princípios obrigatórios:**
- `#[instrument]` em todos os handlers (observabilidade)
- Erros retornam `StatusCode` ou tipo de erro custom (nunca `.unwrap()`)
- Estado partilhado via `State<AppState>` (não globals)
- Validação de input antes de processamento

---

### 3. Debugar erro do compilador (`/rust-debug-compiler-error`)

**Input:** Output completo de `cargo build` ou `cargo check`

**Protocolo de análise:**

1. **Identificar categoria do erro:**
   | Código | Categoria | Solução típica |
   |--------|-----------|----------------|
   | E0382 | Move após uso | Usar `clone()` ou referências `&` |
   | E0502 | Borrow conflict | Reordenar operações, usar `Arc<Mutex<>>` |
   | E0308 | Type mismatch | Verificar tipos, usar `.into()` ou cast explícito |
   | E0277 | Trait not impl | Implementar trait ou usar tipo diferente |
   | E0499 | Multiple mut borrows | Usar `RefCell` ou reestruturar lógica |

2. **Analisar mensagem de erro completa** (incluindo `help:` e `note:`)

3. **Gerar código corrigido** com explicação da causa raiz

4. **Verificar:** `cargo check` passa antes de `cargo build`

**Padrões comuns no AcidaOS Core:**

```rust
// ❌ Move não intencional
let data = fetch_data();
process(data);
log(data); // ERRO: data foi moved

// ✅ Correcto
let data = fetch_data();
process(&data);  // ou process(data.clone())
log(&data);

// ❌ Async + lifetime
async fn handler(req: &Request) -> Response { ... }  // lifetime issue

// ✅ Correcto — owned ou Arc
async fn handler(req: Arc<Request>) -> Response { ... }
```

---

## Quality Gate

Antes de fazer commit:

```bash
cargo check          # zero erros
cargo clippy         # zero warnings
cargo test           # todos os testes passam
cargo fmt --check    # formatação correcta
```

**Standards:**
- Zero `unwrap()` em código de produção — usar `?` ou `expect("mensagem descritiva")`
- Funções async < 50 linhas
- `tracing::instrument` em todas as funções públicas async
- Documentação `///` em todos os tipos e funções públicas

---

## Checklist Entrega

- [ ] `cargo check` sem erros
- [ ] `cargo clippy -- -D warnings` limpo
- [ ] `cargo test` 100% pass
- [ ] Documentação `///` completa
- [ ] Observabilidade: `#[instrument]` nos handlers
- [ ] Sem `.unwrap()` em paths críticos
- [ ] CHANGELOG.md actualizado

---
**Versão**: 1.0.0 | **Autor**: Descomplicar® | **Plugin**: acidaos