zcatsql/claude.md

zcatsql

Tipo: Librería Zig (sin deploy propio) Credenciales: teamdocs/INFRASTRUCTURE/CREDENCIALES.md Cheatsheet: teamdocs/CHEATSHEET.md VCS: git (commits frecuentes)

SQLite wrapper idiomático para Zig 0.15.2+

Parte del ecosistema zcat: zcatui (TUI), zcatgui (GUI), zcatsql (SQLite)

Estado

v1.1 | ~12,000 líneas | 16 módulos | 80 tests

Quick Start

zig build              # Compilar
zig build test         # Tests (80/80)
./zig-out/bin/basic    # Ejemplo

Arquitectura

src/
├── root.zig        # Exports públicos
├── database.zig    # Conexión, transacciones, pragmas, snapshots
├── statement.zig   # Prepared statements, binding, row mapping
├── session.zig     # Change tracking (Session extension)
├── serialize.zig   # Serialize/Deserialize API
├── functions.zig   # UDFs, callbacks, hooks
├── backup.zig      # Backup API, Blob I/O
├── pool.zig        # Connection pool
├── fts5.zig        # Full-text search
├── json.zig        # JSON1 helpers
├── rtree.zig       # R-Tree spatial index
├── vtable.zig      # Virtual tables API
├── types.zig       # Tipos comunes
├── errors.zig      # Mapeo de errores
├── c.zig           # C bindings
└── audit/          # Sistema de auditoría
    ├── mod.zig     # Exports
    ├── log.zig     # AuditLog principal
    ├── entry.zig   # Entry + JSON
    ├── context.zig # User/app context
    ├── index.zig   # File index
    ├── writer.zig  # File rotation
    └── verify.zig  # Hash chain verification

Documentación

Archivo	Contenido
REFERENCE.md	Manual técnico completo (1566 líneas) - API, ejemplos, tipos
docs/AUDIT_LOG_DESIGN.md	Diseño del sistema de auditoría
docs/API.md	Referencia API detallada
docs/ARCHITECTURE.md	Arquitectura del proyecto
README.md	Introducción y ejemplos básicos
examples/basic.zig	Ejemplo ejecutable completo

SQLite Flags

-DSQLITE_THREADSAFE=2          # Multi-thread (required for ConnectionPool)
-DSQLITE_ENABLE_FTS5            # Full-text search
-DSQLITE_ENABLE_JSON1           # JSON functions
-DSQLITE_ENABLE_RTREE           # R-Tree spatial
-DSQLITE_ENABLE_SESSION         # Change tracking
-DSQLITE_ENABLE_SNAPSHOT        # Snapshots
-DSQLITE_ENABLE_COLUMN_METADATA
-DSQLITE_ENABLE_PREUPDATE_HOOK  # Pre-update hooks (audit)

Notas Zig 0.15

Cambio	Solución
ArrayList.init no existe	Usar ArrayListUnmanaged + .empty
callconv(.C)	Cambiar a callconv(.c) (minúscula)
bufferedReader()	Usar readFileAlloc
Strings para SQLite	allocPrint + null terminator
Named params	Incluir prefijo (:name)

Audit Log

var audit = try AuditLog.init(allocator, &db, .{
    .log_dir = "/var/log/audit",
    .app_name = "my_app",
});
defer audit.deinit();
audit.start();  // IMPORTANTE: después de que struct esté en memoria final

Verificar integridad:

var result = try verifyAuditChain(allocator, "/var/log/audit");
defer result.deinit(allocator);
if (!result.valid) { /* ALERTA */ }

---

TEAM STANDARDS

Ubicación: /mnt/cello2/arno/re/recode/teamdocs/

Normas Esenciales

NUNCA:

• Ejecutar binarios en background (&) - shells zombies
• Commit sin testing
• Silenciar warnings
• Duplicar código (verificar common/ primero)
• Archivos >600 líneas
• Modificar scope sin consultar

SIEMPRE:

• DRY - Una función por tarea
• Testing progresivo (compilar + verificar)
• Security commits antes de refactorizaciones
• Actualizar CLAUDE.md cada sesión
• Fragmentar: <400 líneas (core), <200 (utils)

Comunicación

• Directo al grano, sin preámbulos
• Honestidad técnica total
• Si algo está mal, decirlo y explicar

Workflow

1. Leer teamdocs/LAST_UPDATE.md
2. Leer CLAUDE.md del proyecto
3. Implementar con testing progresivo
4. Actualizar documentación
5. Commit tras confirmación usuario

Documentos Clave

• QUICK_REFERENCE.md - Cheat sheet (<1 min)
• NORMAS_TRABAJO_CONSENSUADAS.md - Metodología completa
• NORMAS_PATRONES_DESARROLLO.md - Patrones específicos

---

Git

origin: git@git.reugenio.com:reugenio/zcatsql.git
branch: main

Zig Path

ZIG=/mnt/cello2/arno/re/recode/zig/zig-0.15.2/zig-x86_64-linux-0.15.2/zig

---

CLAUDE CODE + ZLS (LSP)

Claude Code tiene integración LSP con zls (Zig Language Server).

Plugin: $HOME/.claude/plugins/zls-lsp/

Operaciones disponibles:

Operación	Uso
goToDefinition	Navegar a definición de símbolo
findReferences	Encontrar todas las referencias
hover	Info de tipo y documentación
documentSymbol	Símbolos del archivo actual
incomingCalls	Qué funciones llaman a ésta

Documentación: teamdocs/INFRASTRUCTURE/ZLS_LSP_CLAUDE_CODE.md