zcatconfig/CLAUDE.md

ZCATCONFIG - Sistema de Configuracion Declarativo

IMPORTANTE PARA CLAUDE: Lee la seccion "PROTOCOLO DE INICIO" antes de hacer cualquier cosa.

---

PROTOCOLO DE INICIO (LEER PRIMERO)

Paso 1: Leer normas del equipo

/mnt/cello2/arno/re/recode/teamdocs/LAST_UPDATE.md

Paso 2: Verificar estado del proyecto

cd /mnt/cello2/arno/re/recode/zig/zcatconfig
git status
git log --oneline -5
PATH=/mnt/cello2/arno/re/recode/zig/zig-0.15.2/zig-x86_64-linux-0.15.2:$PATH zig build test

---

INFORMACION DEL PROYECTO

Campo	Valor
Nombre	zcatconfig
Version	v0.1.0
Fecha inicio	2025-12-17
Estado	EN DESARROLLO - Estructura inicial
Lenguaje	Zig 0.15.2
Dependencias	Ninguna (Zig puro)

Descripcion

zcatconfig es una libreria para gestion de configuracion declarativa:

• Definicion de variables con metadatos (tipo, default, descripcion, categoria)
• Generacion automatica de struct Config via comptime
• Persistencia a archivo de texto legible
• Validacion de valores
• Sistema Get/Set generico con inline for + @field

---

ORIGEN: zsimifactu config/

Esta libreria extrae y generaliza el sistema de configuracion implementado en zsimifactu.

Archivos originales en zsimifactu:

src/config/
├── config.zig        # Re-exports publicos
├── types.zig         # ConfigVariable, ConfigVarType, Color
├── variables.zig     # Definiciones declarativas (proyecto-especifico)
├── structures.zig    # Config struct (proyecto-especifico)
├── engine.zig        # Meta-engine Get/Set con validacion
└── persistence.zig   # Load/Save archivo texto

Que se extrae a zcatconfig:

• types.zig (completo)
• engine.zig (generalizado)
• persistence.zig (generalizado)

Que queda en el proyecto consumidor:

• variables.zig (definiciones especificas del proyecto)
• structures.zig (struct Config especifico)

---

ARQUITECTURA

┌─────────────────────────────────────────────────────────────────┐
│                      PROYECTO CONSUMIDOR                        │
│                                                                 │
│  variables.zig:                                                 │
│    pub const config_variables = [_]ConfigVariable{              │
│        .{ .name = "auto_save", .var_type = .boolean, ... },     │
│        .{ .name = "font_size", .var_type = .integer, ... },     │
│    };                                                           │
│                                                                 │
│  structures.zig:                                                │
│    pub const Config = struct {                                  │
│        auto_save: bool = true,                                  │
│        font_size: i32 = 14,                                     │
│    };                                                           │
├─────────────────────────────────────────────────────────────────┤
│                         ZCATCONFIG                              │
│                                                                 │
│  types.zig:                                                     │
│    ConfigVariable, ConfigVarType, ConfigResult, Color           │
│                                                                 │
│  engine.zig:                                                    │
│    Engine(comptime variables, comptime ConfigStruct)            │
│    - get(), set(), getByName(), setByName()                     │
│    - Validacion automatica                                      │
│                                                                 │
│  persistence.zig:                                               │
│    - load(config, path, variables)                              │
│    - save(config, path, variables)                              │
│    - Formato: @variable_name: valor  # comentario               │
└─────────────────────────────────────────────────────────────────┘

---

API PROPUESTA

Uso basico

const zcatconfig = @import("zcatconfig");

// En el proyecto consumidor:
const variables = @import("config/variables.zig");
const Config = @import("config/structures.zig").Config;

// Crear engine tipado
const Engine = zcatconfig.Engine(variables.config_variables, Config);

// Uso
var config = Config{};
Engine.load(&config, "app_config.txt") catch {};
config.font_size = 16;
try Engine.save(&config, "app_config.txt");

Tipos de variables soportados

Tipo	Zig Type	Formato archivo
boolean	bool	Si/No
integer	i32	123
float	f32	1.5
string	[]const u8	texto libre
color	Color	RGB(r,g,b)
enum_tipo	enum	NombreVariante

---

COMANDOS

# Compilar
PATH=/mnt/cello2/arno/re/recode/zig/zig-0.15.2/zig-x86_64-linux-0.15.2:$PATH zig build

# Tests
PATH=/mnt/cello2/arno/re/recode/zig/zig-0.15.2/zig-x86_64-linux-0.15.2:$PATH zig build test

---

RUTAS

# Este proyecto
/mnt/cello2/arno/re/recode/zig/zcatconfig/

# Proyecto origen (referencia)
/mnt/cello2/arno/re/recode/zig/zsimifactu/src/config/

# Documentacion equipo
/mnt/cello2/arno/re/recode/teamdocs/

---

PLAN DE TRABAJO

Fase 1: Estructura base - COMPLETADA

• Crear proyecto (build.zig, CLAUDE.md)
• Extraer types.zig de zsimifactu
• Adaptar engine.zig (parametrizar variables y Config)
• Adaptar persistence.zig

Fase 2: Generalizacion - COMPLETADA

• Engine generico con comptime
• Tests unitarios (9 tests)
• Documentacion API

Fase 3: Integracion - EN PROGRESO

• Integrar en zsimifactu como dependencia
• Verificar que zsimifactu funciona igual

---

EQUIPO

• Usuario (R.Eugenio): Desarrollador principal
• Claude: Asistente de programacion (Claude Code / Opus 4.5)

---

HISTORIAL

Fecha	Version	Cambios
2025-12-17	v0.1.0	Proyecto creado, estructura inicial