javi-forge 0.1.0

package/ai-config/skills/database/redis-cache/SKILL.md

@@ -0,0 +1,343 @@
+---
+name: redis-cache
+description: >
+  Redis caching, sessions, pub/sub, rate limiting, and distributed locks.
+  Trigger: redis, cache, session, pub/sub, rate limiting, distributed lock
+
+tools:
+  - Read
+  - Write
+  - Bash
+  - Grep
+
+metadata:
+  author: plataforma-industrial
+  version: "2.0"
+  tags: [cache, redis, real-time, session]
+  updated: "2026-02"
+---
+
+# Redis Cache & Real-time
+
+> Caching, sessions, pub/sub, rate limiting, and distributed locks with Redis.
+
+## Stack
+
+```yaml
+Redis: 7.2+
+go-redis/redis: v9
+ioredis (Node): 5.3+
+redis-py: 5.0+
+```
+
+## When to Use
+
+- Caching frequently accessed data with TTL
+- Session management with expiration
+- Real-time pub/sub between services
+- Rate limiting API endpoints
+- Distributed locks for coordination
+
+## Docker Setup
+
+```yaml
+# docker-compose.yml
+services:
+  redis:
+    image: redis:7-alpine
+    ports:
+      - "6379:6379"
+    volumes:
+      - redis_data:/data
+      - ./config/redis.conf:/usr/local/etc/redis/redis.conf
+    command: redis-server /usr/local/etc/redis/redis.conf
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 5s
+      timeout: 3s
+      retries: 5
+```
+
+### Redis Config
+
+```conf
+# redis.conf
+maxmemory 256mb
+maxmemory-policy allkeys-lru
+save 900 1
+save 300 10
+save 60 10000
+appendonly yes
+appendfsync everysec
+# requirepass your-strong-password  # Production
+```
+
+## Go Connection
+
+```go
+package cache
+
+import (
+    "context"
+    "time"
+    "github.com/redis/go-redis/v9"
+)
+
+type RedisClient struct {
+    client *redis.Client
+}
+
+func NewRedisClient(addr, password string, db int) (*RedisClient, error) {
+    client := redis.NewClient(&redis.Options{
+        Addr:         addr,
+        Password:     password,
+        DB:           db,
+        PoolSize:     100,
+        MinIdleConns: 10,
+        MaxRetries:   3,
+        DialTimeout:  5 * time.Second,
+        ReadTimeout:  3 * time.Second,
+        WriteTimeout: 3 * time.Second,
+    })
+
+    ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+    defer cancel()
+
+    if err := client.Ping(ctx).Err(); err != nil {
+        return nil, err
+    }
+    return &RedisClient{client: client}, nil
+}
+```
+
+## Cache-Aside Pattern
+
+```go
+func (c *Cache) GetOrLoad(ctx context.Context, key string, loader func() (any, error)) (any, error) {
+    // Try cache first
+    data, err := c.redis.Get(ctx, key).Bytes()
+    if err == nil {
+        var result any
+        json.Unmarshal(data, &result)
+        return result, nil
+    }
+    if err != redis.Nil {
+        return nil, err
+    }
+
+    // Cache miss - load from source
+    result, err := loader()
+    if err != nil {
+        return nil, err
+    }
+
+    // Store in cache (async)
+    go func() {
+        ctx, cancel := context.WithTimeout(context.Background(), time.Second)
+        defer cancel()
+        data, _ := json.Marshal(result)
+        c.redis.Set(ctx, key, data, 5*time.Minute)
+    }()
+
+    return result, nil
+}
+```
+
+## Session Management
+
+```go
+const sessionTTL = 24 * time.Hour
+
+type Session struct {
+    ID        string    `json:"id"`
+    UserID    string    `json:"user_id"`
+    TenantID  string    `json:"tenant_id"`
+    Role      string    `json:"role"`
+    ExpiresAt time.Time `json:"expires_at"`
+}
+
+func (s *SessionStore) Create(ctx context.Context, userID, tenantID, role string) (*Session, error) {
+    session := &Session{
+        ID:        uuid.New().String(),
+        UserID:    userID,
+        TenantID:  tenantID,
+        Role:      role,
+        ExpiresAt: time.Now().Add(sessionTTL),
+    }
+    data, _ := json.Marshal(session)
+
+    pipe := s.redis.Pipeline()
+    pipe.Set(ctx, "session:"+session.ID, data, sessionTTL)
+    pipe.SAdd(ctx, "user:"+userID+":sessions", session.ID)
+    pipe.Expire(ctx, "user:"+userID+":sessions", sessionTTL)
+    _, err := pipe.Exec(ctx)
+    return session, err
+}
+
+func (s *SessionStore) DeleteAllForUser(ctx context.Context, userID string) error {
+    sessionIDs, _ := s.redis.SMembers(ctx, "user:"+userID+":sessions").Result()
+    keys := make([]string, len(sessionIDs)+1)
+    for i, id := range sessionIDs {
+        keys[i] = "session:" + id
+    }
+    keys[len(sessionIDs)] = "user:" + userID + ":sessions"
+    return s.redis.Del(ctx, keys...).Err()
+}
+```
+
+## Pub/Sub
+
+```go
+// Publisher
+func (p *Publisher) Publish(ctx context.Context, channel string, event Event) error {
+    data, _ := json.Marshal(event)
+    return p.redis.Publish(ctx, channel, data).Err()
+}
+
+// Subscriber
+func (s *Subscriber) Subscribe(ctx context.Context, channels ...string) error {
+    pubsub := s.redis.Subscribe(ctx, channels...)
+    defer pubsub.Close()
+
+    for msg := range pubsub.Channel() {
+        var event Event
+        json.Unmarshal([]byte(msg.Payload), &event)
+        for _, handler := range s.handlers[event.Type] {
+            handler(ctx, event)
+        }
+    }
+    return nil
+}
+```
+
+## Rate Limiting (Sliding Window)
+
+```go
+func (rl *RateLimiter) Allow(ctx context.Context, key string) (bool, int, error) {
+    now := time.Now().UnixMilli()
+    windowStart := now - rl.window.Milliseconds()
+    redisKey := "ratelimit:" + key
+
+    pipe := rl.redis.Pipeline()
+    pipe.ZRemRangeByScore(ctx, redisKey, "0", fmt.Sprintf("%d", windowStart))
+    countCmd := pipe.ZCard(ctx, redisKey)
+    pipe.ZAdd(ctx, redisKey, redis.Z{Score: float64(now), Member: now})
+    pipe.Expire(ctx, redisKey, rl.window)
+    pipe.Exec(ctx)
+
+    count := int(countCmd.Val())
+    remaining := rl.limit - count - 1
+    if remaining < 0 {
+        remaining = 0
+    }
+    return count < rl.limit, remaining, nil
+}
+```
+
+## Distributed Lock
+
+```go
+func NewLock(redis *redis.Client, key string, ttl time.Duration) *DistributedLock {
+    return &DistributedLock{
+        redis: redis,
+        key:   "lock:" + key,
+        value: uuid.New().String(),
+        ttl:   ttl,
+    }
+}
+
+func (l *DistributedLock) Acquire(ctx context.Context) error {
+    success, _ := l.redis.SetNX(ctx, l.key, l.value, l.ttl).Result()
+    if !success {
+        return ErrLockNotAcquired
+    }
+    return nil
+}
+
+func (l *DistributedLock) Release(ctx context.Context) error {
+    script := redis.NewScript(`
+        if redis.call("GET", KEYS[1]) == ARGV[1] then
+            return redis.call("DEL", KEYS[1])
+        end
+        return 0
+    `)
+    _, err := script.Run(ctx, l.redis, []string{l.key}, l.value).Result()
+    return err
+}
+
+func WithLock(ctx context.Context, redis *redis.Client, key string, ttl time.Duration, fn func() error) error {
+    lock := NewLock(redis, key, ttl)
+    if err := lock.Acquire(ctx); err != nil {
+        return err
+    }
+    defer lock.Release(ctx)
+    return fn()
+}
+```
+
+## TypeScript/Node.js
+
+```typescript
+import Redis from 'ioredis';
+
+export const redis = new Redis({
+  host: process.env.REDIS_HOST || 'localhost',
+  port: parseInt(process.env.REDIS_PORT || '6379'),
+  password: process.env.REDIS_PASSWORD,
+  maxRetriesPerRequest: 3,
+});
+
+// Pub/Sub requires separate connections
+export const publisher = new Redis(/* config */);
+export const subscriber = new Redis(/* config */);
+```
+
+## Best Practices
+
+| Practice | Description |
+|----------|-------------|
+| Always set TTL | Avoid memory issues with `Set(key, val, TTL)` |
+| Use pipelines | Single round-trip for batch ops |
+| Namespace keys | `tenant:{id}:sensor:{id}` format |
+| Handle redis.Nil | Not an error, just cache miss |
+| Separate pub/sub conn | Pub/sub blocks, use dedicated client |
+
+### Data Structure Selection
+
+```
+String    - Simple cache, counters
+Hash      - Objects with multiple fields
+List      - Queues, recent items
+Set       - Tags, unique items
+Sorted Set - Leaderboards, time-series
+Stream    - Event logs, message queues
+```
+
+## Quick Reference
+
+| Task | Command |
+|------|---------|
+| Set with TTL | `SET key value EX 300` |
+| Get | `GET key` |
+| Delete | `DEL key1 key2` |
+| Publish | `PUBLISH channel message` |
+| Rate limit check | `ZRANGEBYSCORE + ZADD` |
+
+## Resources
+
+- [Redis Documentation](https://redis.io/docs/)
+- [go-redis Guide](https://redis.uptrace.dev/)
+- [ioredis Documentation](https://github.com/redis/ioredis)
+
+---
+
+## Changelog
+
+- **2.0** - Condensed from Plataforma Industrial SKILL-REDIS
+
+## Related Skills
+
+- `timescaledb`: Database caching layer
+- `pgx-postgres`: Query result caching
+- `chi-router`: Go cache middleware
+- `fastapi`: Python cache patterns

package/ai-config/skills/database/sqlite-embedded/SKILL.md

@@ -0,0 +1,388 @@
+---
+name: sqlite-embedded
+description: >
+  SQLite embedded database for edge/offline scenarios with sync queue patterns.
+  Trigger: sqlite, embedded database, offline, edge, sync queue, local storage
+
+tools:
+  - Read
+  - Write
+  - Bash
+  - Grep
+
+metadata:
+  author: plataforma-industrial
+  version: "2.0"
+  tags: [sqlite, edge, embedded, offline, database]
+  updated: "2026-02"
+---
+
+# SQLite Embedded Database
+
+> Edge/offline embedded database with zero configuration and sync queue patterns.
+
+## Stack
+
+```yaml
+SQLite: 3.45+
+Driver Go: modernc.org/sqlite  # Pure Go, no CGO
+Driver Rust: rusqlite 0.31+
+Mobile: @capacitor-community/sqlite
+```
+
+## When to Use
+
+- Edge/offline-first applications
+- Local configuration storage
+- Sync queue for pending cloud operations
+- Low-footprint deployments (<5MB RAM)
+- Single-file database with easy backup
+
+## Optimal PRAGMAs
+
+```sql
+PRAGMA journal_mode = WAL;          -- Write-Ahead Logging (better concurrency)
+PRAGMA synchronous = NORMAL;        -- Balance durability/speed
+PRAGMA foreign_keys = ON;           -- Referential integrity
+PRAGMA cache_size = -64000;         -- 64MB cache
+PRAGMA mmap_size = 268435456;       -- 256MB memory-mapped I/O
+PRAGMA busy_timeout = 5000;         -- 5s retry if locked
+PRAGMA temp_store = MEMORY;         -- Temp tables in memory
+```
+
+## Go Connection (Pure Go, No CGO)
+
+```go
+package db
+
+import (
+    "context"
+    "database/sql"
+    "fmt"
+    "time"
+    _ "modernc.org/sqlite"
+)
+
+type SQLiteConfig struct {
+    Path            string
+    MaxOpenConns    int
+    MaxIdleConns    int
+    ConnMaxLifetime time.Duration
+}
+
+func NewSQLiteDB(cfg SQLiteConfig) (*sql.DB, error) {
+    dsn := fmt.Sprintf(
+        "file:%s?_journal_mode=WAL&_synchronous=NORMAL&_foreign_keys=ON&_busy_timeout=5000&_cache_size=-64000",
+        cfg.Path,
+    )
+
+    db, err := sql.Open("sqlite", dsn)
+    if err != nil {
+        return nil, fmt.Errorf("open sqlite: %w", err)
+    }
+
+    // SQLite: 1 writer, multiple readers
+    db.SetMaxOpenConns(cfg.MaxOpenConns)  // Typically 1-4
+    db.SetMaxIdleConns(cfg.MaxIdleConns)
+    db.SetConnMaxLifetime(cfg.ConnMaxLifetime)
+
+    ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+    defer cancel()
+    if err := db.PingContext(ctx); err != nil {
+        return nil, fmt.Errorf("ping sqlite: %w", err)
+    }
+    return db, nil
+}
+
+func DefaultConfig(path string) SQLiteConfig {
+    return SQLiteConfig{
+        Path:            path,
+        MaxOpenConns:    4,
+        MaxIdleConns:    2,
+        ConnMaxLifetime: time.Hour,
+    }
+}
+```
+
+## Rust Connection
+
+```rust
+use rusqlite::{Connection, OpenFlags, Result};
+use std::path::Path;
+
+pub struct SqliteDb {
+    conn: Connection,
+}
+
+impl SqliteDb {
+    pub fn new(path: &Path) -> Result<Self> {
+        let conn = Connection::open_with_flags(
+            path,
+            OpenFlags::SQLITE_OPEN_READ_WRITE
+                | OpenFlags::SQLITE_OPEN_CREATE
+                | OpenFlags::SQLITE_OPEN_NO_MUTEX,
+        )?;
+
+        conn.execute_batch("
+            PRAGMA journal_mode = WAL;
+            PRAGMA synchronous = NORMAL;
+            PRAGMA foreign_keys = ON;
+            PRAGMA cache_size = -64000;
+            PRAGMA busy_timeout = 5000;
+        ")?;
+
+        Ok(Self { conn })
+    }
+}
+```
+
+## Schema Patterns
+
+### Configuration Table
+
+```sql
+CREATE TABLE IF NOT EXISTS sensors (
+    id TEXT PRIMARY KEY,
+    plant_id TEXT NOT NULL REFERENCES plants(id) ON DELETE CASCADE,
+    name TEXT NOT NULL,
+    type TEXT NOT NULL,
+    unit TEXT NOT NULL,
+    modbus_address INTEGER,
+    modbus_register INTEGER,
+    scale_factor REAL DEFAULT 1.0,
+    warning_low REAL,
+    warning_high REAL,
+    critical_low REAL,
+    critical_high REAL,
+    read_interval_secs INTEGER DEFAULT 10,
+    is_active INTEGER NOT NULL DEFAULT 1,
+    metadata TEXT DEFAULT '{}',
+    created_at TEXT NOT NULL DEFAULT (datetime('now')),
+    updated_at TEXT NOT NULL DEFAULT (datetime('now'))
+);
+
+CREATE INDEX idx_sensors_plant ON sensors(plant_id);
+CREATE INDEX idx_sensors_active ON sensors(is_active);
+```
+
+### Recent Readings Cache (with cleanup trigger)
+
+```sql
+CREATE TABLE IF NOT EXISTS sensor_readings_recent (
+    id TEXT PRIMARY KEY,
+    sensor_id TEXT NOT NULL REFERENCES sensors(id) ON DELETE CASCADE,
+    value REAL NOT NULL,
+    quality TEXT DEFAULT 'good' CHECK (quality IN ('good', 'uncertain', 'bad')),
+    timestamp TEXT NOT NULL,
+    synced INTEGER NOT NULL DEFAULT 0,
+    created_at TEXT NOT NULL DEFAULT (datetime('now'))
+);
+
+CREATE INDEX idx_readings_sensor ON sensor_readings_recent(sensor_id, timestamp DESC);
+CREATE INDEX idx_readings_synced ON sensor_readings_recent(synced) WHERE synced = 0;
+
+-- Auto-cleanup: keep only last 1000 per sensor
+CREATE TRIGGER IF NOT EXISTS trg_readings_cleanup
+AFTER INSERT ON sensor_readings_recent
+BEGIN
+    DELETE FROM sensor_readings_recent
+    WHERE id IN (
+        SELECT id FROM sensor_readings_recent
+        WHERE sensor_id = NEW.sensor_id
+        ORDER BY timestamp DESC
+        LIMIT -1 OFFSET 1000
+    );
+END;
+```
+
+### Sync Queue
+
+```sql
+CREATE TABLE IF NOT EXISTS sync_queue (
+    id TEXT PRIMARY KEY,
+    plant_id TEXT NOT NULL,
+    entity_type TEXT NOT NULL,
+    entity_id TEXT NOT NULL,
+    operation TEXT NOT NULL CHECK (operation IN ('create', 'update', 'delete')),
+    payload TEXT NOT NULL,
+    priority INTEGER NOT NULL DEFAULT 0,
+    retries INTEGER NOT NULL DEFAULT 0,
+    max_retries INTEGER NOT NULL DEFAULT 5,
+    last_error TEXT,
+    next_retry_at TEXT,
+    created_at TEXT NOT NULL DEFAULT (datetime('now')),
+    processed_at TEXT
+);
+
+CREATE INDEX idx_sync_queue_pending ON sync_queue(priority DESC, created_at)
+    WHERE processed_at IS NULL;
+```
+
+## Sync Queue Repository
+
+```go
+type SyncItem struct {
+    ID         string          `json:"id"`
+    PlantID    string          `json:"plant_id"`
+    EntityType string          `json:"entity_type"`
+    EntityID   string          `json:"entity_id"`
+    Operation  string          `json:"operation"`
+    Payload    json.RawMessage `json:"payload"`
+    Priority   int             `json:"priority"`
+    Retries    int             `json:"retries"`
+    MaxRetries int             `json:"max_retries"`
+}
+
+func (r *SyncQueueRepository) GetPending(ctx context.Context, limit int) ([]SyncItem, error) {
+    query := `
+        SELECT id, plant_id, entity_type, entity_id, operation, payload,
+               priority, retries, max_retries, last_error, created_at
+        FROM sync_queue
+        WHERE processed_at IS NULL
+          AND (next_retry_at IS NULL OR next_retry_at <= datetime('now'))
+        ORDER BY priority DESC, created_at ASC
+        LIMIT ?
+    `
+    // ... scan rows
+}
+
+func (r *SyncQueueRepository) MarkFailed(ctx context.Context, id string, errMsg string) error {
+    query := `
+        UPDATE sync_queue
+        SET retries = retries + 1,
+            last_error = ?,
+            next_retry_at = datetime('now', '+' || (retries + 1) * 30 || ' seconds')
+        WHERE id = ?
+    `
+    _, err := r.db.ExecContext(ctx, query, errMsg, id)
+    return err
+}
+```
+
+## Batch Insert Pattern
+
+```go
+func (r *ReadingRepository) InsertBatch(ctx context.Context, readings []Reading) error {
+    if len(readings) == 0 {
+        return nil
+    }
+
+    tx, err := r.db.BeginTx(ctx, nil)
+    if err != nil {
+        return err
+    }
+    defer tx.Rollback()
+
+    placeholders := make([]string, len(readings))
+    args := make([]any, 0, len(readings)*6)
+
+    for i, rd := range readings {
+        placeholders[i] = "(?, ?, ?, ?, ?, ?)"
+        args = append(args, rd.ID, rd.SensorID, rd.Value, rd.Quality, rd.RawValue, rd.Timestamp)
+    }
+
+    query := `INSERT INTO sensor_readings_recent (id, sensor_id, value, quality, raw_value, timestamp)
+              VALUES ` + strings.Join(placeholders, ", ")
+    _, err = tx.ExecContext(ctx, query, args...)
+    if err != nil {
+        return err
+    }
+    return tx.Commit()
+}
+```
+
+## Useful Views
+
+```sql
+-- Latest reading per sensor with status
+CREATE VIEW IF NOT EXISTS v_sensor_latest_readings AS
+SELECT
+    s.id AS sensor_id,
+    s.name AS sensor_name,
+    r.value,
+    r.timestamp,
+    CASE
+        WHEN r.value IS NULL THEN 'no_data'
+        WHEN s.critical_low IS NOT NULL AND r.value < s.critical_low THEN 'critical_low'
+        WHEN s.critical_high IS NOT NULL AND r.value > s.critical_high THEN 'critical_high'
+        WHEN s.warning_low IS NOT NULL AND r.value < s.warning_low THEN 'warning_low'
+        WHEN s.warning_high IS NOT NULL AND r.value > s.warning_high THEN 'warning_high'
+        ELSE 'normal'
+    END AS status
+FROM sensors s
+LEFT JOIN (
+    SELECT sensor_id, value, timestamp,
+           ROW_NUMBER() OVER (PARTITION BY sensor_id ORDER BY timestamp DESC) AS rn
+    FROM sensor_readings_recent
+) r ON r.sensor_id = s.id AND r.rn = 1
+WHERE s.is_active = 1;
+```
+
+## Backup (Hot Backup with WAL)
+
+```go
+func BackupDatabase(ctx context.Context, db *sql.DB, destDir string) (string, error) {
+    filename := fmt.Sprintf("backup_%s.db", time.Now().Format("20060102_150405"))
+    destPath := filepath.Join(destDir, filename)
+
+    // VACUUM INTO creates consistent backup without stopping
+    query := fmt.Sprintf("VACUUM INTO '%s'", destPath)
+    _, err := db.ExecContext(ctx, query)
+    return destPath, err
+}
+```
+
+## SQLite vs PostgreSQL Syntax
+
+| Aspect | SQLite | PostgreSQL |
+|--------|--------|------------|
+| Datetime | `datetime('now')` | `NOW()` |
+| Interval | `datetime('now', '-1 hour')` | `NOW() - INTERVAL '1 hour'` |
+| Boolean | `INTEGER (0/1)` | `BOOLEAN` |
+| UUID | `TEXT` | `UUID` |
+| Auto-ID | `INTEGER PRIMARY KEY` | `SERIAL` |
+| JSON | `TEXT + json_*()` | `JSONB` |
+
+## Performance Tips
+
+```sql
+-- Partial indexes (smaller, faster)
+CREATE INDEX idx_readings_unsynced ON sensor_readings_recent(synced)
+    WHERE synced = 0;
+
+-- Check query plan
+EXPLAIN QUERY PLAN
+SELECT * FROM sensor_readings_recent WHERE sensor_id = 'abc';
+
+-- Update statistics
+ANALYZE;
+```
+
+## Quick Reference
+
+| Task | Command |
+|------|---------|
+| Check integrity | `PRAGMA integrity_check;` |
+| Enable WAL | `PRAGMA journal_mode = WAL;` |
+| Set busy timeout | `PRAGMA busy_timeout = 5000;` |
+| Hot backup | `VACUUM INTO 'backup.db'` |
+| DB size | `SELECT page_count * page_size FROM pragma_page_count(), pragma_page_size();` |
+
+## Resources
+
+- [SQLite Documentation](https://sqlite.org/docs.html)
+- [modernc.org/sqlite](https://pkg.go.dev/modernc.org/sqlite)
+- [rusqlite](https://docs.rs/rusqlite)
+
+---
+
+## Changelog
+
+- **2.0** - Condensed from Plataforma Industrial SKILL-SQLITE
+
+## Related Skills
+
+- `mobile-ionic`: Offline-first mobile apps
+- `ionic-capacitor`: Native SQLite access
+- `duckdb-analytics`: Embedded analytics
+- `rust-systems`: Embedded Rust apps