Imported from Mario-pereyra/ProteusdDbCli (AGENTS.md). Install upstream with npx skills add Mario-pereyra/ProteusdDbCli. Copyright stays with the author.

AGENTS.md — Reglas del Proyecto para Agentes IA

Este archivo es el contrato de comportamiento para cualquier agente de IA que trabaje sobre protheus-db-cli. Léelo completo antes de modificar cualquier archivo.

1. Identidad del Proyecto

protheus-db-cli es una CLI de precisión en Rust que actúa como puente entre agentes de IA y la base de datos MSSQL del ERP TOTVS Protheus. Su diseño prioriza:

• Eficiencia de tokens: minimizar datos devueltos mediante sondeo incremental (DSR-SQL)
• Composabilidad Unix: salida CSV pipeable con grep, awk, jq, ConvertFrom-Csv
• Seguridad de base de datos: ninguna operación destructiva puede ejecutarse

2. Comandos de Auto-Verificación (OBLIGATORIOS)

Antes de dar por terminada cualquier tarea que modifique código Rust, ejecuta en orden:

# 1. Verificar compilación sin errores
cargo check

# 2. Ejecutar suite de tests unitarios
cargo test

# 3. Verificar que no hay warnings de compilación activos
cargo check 2>&1 | grep -E "^warning:" | wc -l
# Resultado aceptable: 0 warnings nuevos introducidos por tu cambio

Criterio de aceptación: cargo check + cargo test deben salir con exit code 0. Si cualquiera falla, la tarea NO está terminada. No generes una respuesta final hasta resolverlo.

3. Fronteras y Límites Absolutos

Las siguientes reglas son no negociables. Violarlas rompe la razón de existir de esta CLI.

3.1 Dual Stream Policy — NUNCA violar

stdout → SOLO datos en CSV (filas + headers)
stderr → SOLO logs, errores, diagnóstico (eprintln!, tracing)

• Prohibido: usar println! para mensajes de log o error
• Prohibido: usar eprintln! para emitir datos estructurados
• Prohibido: mezclar texto libre con CSV en stdout

Si necesitas emitir un mensaje informativo, usa siempre eprintln!("[nivel] mensaje").

3.2 Módulo de Seguridad — NUNCA eliminar ni debilitar

El archivo src/security.rs y su función analyze_query_with_limit deben invocarse antes de toda ejecución SQL en todos los handlers de main.rs.

• Prohibido: ejecutar SQL directamente sin pasar por security::analyze_query_with_limit
• Prohibido: eliminar o comentar la lista BLOCKED_KEYWORDS en security.rs
• Prohibido: reducir el número de keywords bloqueadas (solo se puede ampliar)
• Prohibido: ignorar un SecurityResult::Rejected y continuar la ejecución

3.3 Exit Codes — NUNCA reutilizar ni redefinir

Si necesitas un nuevo código de error, usa valores ≥ 50 y documéntalo aquí.

3.4 Taxonomía de Subcomandos — NUNCA cambiar nombres existentes

La estructura data query / schema probe / schema fields / conn test es el contrato público de la CLI. Los agentes que consumen esta herramienta tienen instrucciones hardcodeadas con estos nombres. Cambiarlos rompe la compatibilidad sin previo aviso.

• Permitido: agregar nuevos subcomandos bajo los dominios existentes
• Prohibido: renombrar o eliminar subcomandos ya publicados

4. Convenciones de Código

4.1 Rust

• Manejo de errores: usa Result<T, String> para errores de negocio, no unwrap() en código de producción
• Async: todos los handlers de dominio son async fn — no bloquear el runtime con operaciones síncronas IO
• Logging: todos los mensajes de diagnóstico a stderr con prefijo [nivel]:

  [info]     → operaciones normales
  [warn]     → situaciones inesperadas no fatales
  [error]    → fallos que detienen la operación
  [security] → eventos del módulo SkillFortify
  [debug]    → información de diagnóstico detallada
  

4.2 Tests

• Los tests unitarios viven en un módulo #[cfg(test)] dentro del mismo archivo (security.rs)
• No agregar dependencias externas de test sin justificación
• Cualquier nuevo comportamiento del módulo de seguridad debe tener test unitario

4.3 Dependencias

Antes de agregar una nueva dependencia a Cargo.toml, verifica:

1. ¿Ya existe una crate en el proyecto que cubre esa necesidad?
2. ¿Es compatible con el modelo async de tokio?
3. ¿Agrega compilación de C/C++ (build scripts complejos)? — evitar si es posible

5. Protocolo DSR-SQL — Orden de Operaciones

Cuando generes o ejecutes queries para explorar la base de datos Protheus, sigue este orden:

Paso 1 → schema probe --table <ALIAS>    # Validar existencia en SX2
Paso 2 → schema fields --table <ALIAS>   # Entender campos disponibles en SX3
Paso 3 → data query --sql "SELECT ..."   # Ejecutar query informada

Nunca saltes al Paso 3 sin haber confirmado la estructura en pasos 1 y 2. Los nombres de campo en Protheus son crípticos (A1_COD, A1_NOME, A1_CGC) y varían según la versión del ERP. Asumir sin sondear genera queries que fallan.

Filtro anti-registros eliminados (OBLIGATORIO)

Protheus usa eliminación lógica, NO física. Todo SELECT sobre tablas transaccionales debe incluir:

WHERE D_E_L_E_T_ <> '*'

Sin este filtro, los resultados incluyen registros que el negocio considera eliminados.

6. Estructura de Archivos — Qué Toca Qué

src/main.rs      → Orquestación CLI, subcomandos, resolve_config
                   NO contiene lógica de negocio ni queries SQL directas
                   NO contiene lógica de seguridad

src/db.rs        → Conexión TDS, ejecución SQL, serialización CSV
                   SOLO se invoca desde main.rs DESPUÉS de pasar por security
                   NO conoce nada de los subcomandos

src/security.rs  → Analizador estático de SQL
                   SOLO recibe strings, NO hace IO
                   DEBE ser el primer paso antes de cualquier ejecución

7. Lo que Está Fuera de Alcance

Las siguientes funcionalidades están fuera del scope de esta CLI. No las implementes sin una discusión explícita con el equipo:

• Autenticación Windows (Kerberos / Active Directory) — actualmente solo SQL Server Auth
• Soporte para múltiples result sets combinados en un solo CSV
• Streaming de resultados mayores a memoria disponible
• Modo interactivo (REPL) — esta CLI es estrictamente un comando único
• Escritura/modificación de datos — el propósito es lectura de solo lectura

8. Checklist de PR / Entrega

Antes de declarar una tarea como completada, confirma:

• cargo check → exit 0
• cargo test → exit 0, todos los tests pasan
• No se mezcla stdout/stderr en ningún código nuevo
• Todo nuevo SQL pasa por security::analyze_query_with_limit
• Los exit codes nuevos usan valores ≥ 50 y están documentados aquí
• Si se agregan subcomandos, están documentados en README.md y en el SKILL.md