nwinread 1.1.0 → 1.1.1

package/CONTRIBUTING.md

@@ -0,0 +1,64 @@
+# Contributing to nwinread
+
+¡Gracias por tu interés en contribuir a **nwinread**! 
+
+## 🚀 Quick Start for Contributors
+
+```bash
+# 1. Fork & Clone
+git clone https://github.com/your-username/nwinread.git
+cd nwinread
+
+# 2. Setup Development Environment  
+npm install
+npm run build
+npm test
+
+# 3. Verify Setup
+npm run verify
+```
+
+## 📋 Development Workflow
+
+1. **Make your changes** to the C++ code in `native/` or JavaScript in `index.js`
+2. **Test locally**: `npm run build && npm test`
+3. **Generate prebuilds**: `npm run prebuildify` (optional)
+4. **Submit PR** with clear description
+
+## 🔧 Available Scripts
+
+```bash
+npm run build        # Compile native module locally
+npm run prebuildify  # Generate precompiled binary for current platform
+npm run clean        # Clean build artifacts
+npm test            # Run functionality tests
+npm run verify      # Comprehensive setup verification
+```
+
+## 📚 Documentation
+
+For detailed information about:
+- **N-API setup and configuration** → See [NAPI-SETUP.md](NAPI-SETUP.md)
+- **Release process and CI/CD** → See [NAPI-SETUP.md](NAPI-SETUP.md)
+- **Supported Node.js versions** → See [README.md](README.md)
+
+## 🐛 Reporting Issues
+
+When reporting issues, please include:
+- Node.js version (`node --version`)
+- Windows version  
+- Error message and stack trace
+- Minimal reproduction code
+
+## 💡 Feature Requests
+
+Feel free to suggest new features via GitHub Issues. Popular requests:
+- Support for additional event log channels
+- Performance optimizations
+- Additional filtering options
+
+## 🙏 Questions?
+
+- Check existing issues
+- Read [NAPI-SETUP.md](NAPI-SETUP.md) for technical details
+- Open a discussion for general questions

package/NAPI-SETUP.md

@@ -1,23 +1,40 @@
 # Guía de Binarios Universales con N-API
 
-Este documento explica cómo se configuró **nwinread** para distribuir binarios universales usando N-API y prebuildify.
+Este documento explica cómo se configuró **nwinread** para distribuir binarios universales usando N-API, node-gyp-build y prebuildify.
 
 ## ✨ ¿Qué se logró?
 
 - **Binarios Universales**: Compatible con múltiples versiones de Node.js sin recompilación
 - **Distribución Precompilada**: Los usuarios no necesitan herramientas de compilación
 - **CI/CD Automatizado**: GitHub Actions compila binarios para múltiples plataformas
-- **Carga Inteligente**: Fallback automático si no hay binario precompilado
+- **Carga Inteligente**: `node-gyp-build` maneja automáticamente la selección de binarios
+- **Soporte Amplio**: Node.js 16+ con binarios precompilados, 10+ con compilación local
+
+## 📊 Versiones de Node.js Soportadas
+
+### ✅ **Soporte Principal (Binarios Precompilados)**
+| Node.js | N-API | Estado | Instalación |
+|---------|--------|--------|-------------|
+| 16.x | 8 | ✅ LTS | Instantánea |
+| 18.x | 8-9 | ✅ LTS | Instantánea | 
+| 20.x | 8-9 | ✅ LTS | Instantánea |
+| 22.x | 8-9 | ✅ Current | Instantánea |
+
+### ⚠️ **Soporte Retrocompatible (Compilación Local)**
+| Node.js | N-API | Estado | Instalación |
+|---------|--------|--------|-------------|
+| 10.x-14.x | 3-7 | ⚠️ EOL | Requiere Build Tools |
 
 ## 🏗️ Configuración Implementada
 
-### 1. Package.json Updates
+### 1. Package.json Configuración Actual
 ```json
 {
   "dependencies": {
-    "node-addon-api": "^8.0.0"
+    "node-gyp-build": "^4.8.0"
   },
   "devDependencies": {
+    "node-addon-api": "^8.0.0",
     "prebuildify": "^6.0.0",
     "prebuildify-cross": "^5.0.0"
   },
@@ -25,6 +42,7 @@ Este documento explica cómo se configuró **nwinread** para distribuir binarios
     "napi_versions": [3, 4, 5, 6, 7, 8, 9]
   },
   "scripts": {
+    "install": "node-gyp-build",
     "prebuildify": "prebuildify --napi --strip",
     "prebuild": "npm run prebuildify",
     "prepublishOnly": "npm run prebuild"
@@ -32,45 +50,179 @@ Este documento explica cómo se configuró **nwinread** para distribuir binarios
 }
 ```
 
+**Cambios Clave:**
+- ✅ `node-gyp-build` como dependencia principal (carga automática)
+- ✅ `node-addon-api` movido a devDependencies 
+- ✅ Script `install` para manejo automático de binarios
+- ❌ Removido `gypfile: true` (causaba compilación forzada)
+
 ### 2. Binding.gyp Optimizado
 - Configuración N-API con `NAPI_VERSION=8`
 - Headers de `node-addon-api` incluidos
 - Configuración para excluir excepciones C++
 
-### 3. Index.js con Carga Inteligente
+### 3. Index.js Simplificado con node-gyp-build
 ```javascript
-// Intenta cargar binario precompilado
-const prebuiltPath = join(__dirname, 'prebuilds', `${platform}-${arch}`, 'nwinread.node');
-native = require(prebuiltPath);
-
-// Fallback a compilación local si falla
-native = require('./build/Release/eventlog.node');
+// Carga automática de binario (precompilado o local)
+const native = require('node-gyp-build')(__dirname);
 ```
 
+**Ventajas de node-gyp-build:**
+- 🔍 **Detección automática** de plataforma y arquitectura
+- 📦 **Prioriza binarios precompilados** en `prebuilds/`
+- 🔄 **Fallback automático** a compilación local si no hay binario
+- ⚡ **Sin lógica manual** de detección de plataformas
+- 🛡️ **Manejo de errores robusto** incorporado
+
 ### 4. CI/CD con GitHub Actions
 - Compila automáticamente para Windows x64 y ARM64
 - Compatible con Node.js 16, 18, 20, 22
 - Publica automáticamente cuando se hace un tag
 
-## 🚀 Flujo de Distribución
+## 🚀 Proceso Completo de Release y Distribución
 
-1. **Desarrollo Local**:
-   ```bash
-   npm run build          # Compila localmente
-   npm run prebuildify    # Genera binario precompilado
-   npm test              # Verifica funcionamiento
-   npm run verify        # Verifica configuración completa
-   ```
+### 📋 **PASO 1: Preparación Pre-Release (Local)**
 
-2. **Preparar Release**:
-   ```bash
-   npm version patch     # Incrementa versión
-   git push origin --tags # Despliega CI/CD
-   ```
+```bash
+# 1. Verificar que todo funcione
+npm test
+npm run verify
+
+# 2. Limpiar builds anteriores
+npm run clean
+
+# 3. Generar binarios precompilados para tu plataforma
+npm run prebuildify
+
+# 4. Verificar que se crearon los binarios
+ls -la prebuilds/
+# Deberías ver: prebuilds/win32-x64/nwinread.node
+
+# 5. Probar carga automática
+node -e "console.log('✅', require('./index.js'))"
+```
+
+### 🏷️ **PASO 2: Crear Release**
+
+```bash
+# 1. Incrementar versión (automáticamente ejecuta prepublishOnly)
+npm version patch    # 1.1.0 -> 1.1.1 (bug fixes)
+npm version minor    # 1.1.0 -> 1.2.0 (nuevas features)
+npm version major    # 1.1.0 -> 2.0.0 (breaking changes)
+
+# 2. Subir tag al repositorio (dispara CI/CD)
+git push origin --tags
+
+# 3. Opcional: subir cambios también
+git push origin main
+```
+
+### 🤖 **PASO 3: CI/CD Automático (GitHub Actions)**
+
+Una vez que pushes el tag, GitHub Actions automáticamente:
+
+```yaml
+# Matriz de compilación automática:
+- Windows x64 + Node.js [16, 18, 20, 22]
+- Windows ARM64 + Node.js [16, 18, 20, 22] 
+
+# Proceso automático:
+1. ✅ Checkout código fuente
+2. ✅ Setup entorno para cada combinación
+3. ✅ npm ci (instalar dependencias)
+4. ✅ npm run prebuildify (generar binario)
+5. ✅ Collect artifacts (recopilar binarios)
+6. ✅ npm publish (solo en releases)
+```
+
+### 📦 **PASO 4: Verificación Post-Release**
+
+```bash
+# Esperar ~5-10 minutos después del push del tag
+
+# 1. Verificar que el package se publicó
+npm info nwinread
 
-3. **CI/CD Automático** (GitHub Actions):
-   - Compila para múltiples plataformas/arquitecturas
-   - Genera todos los binarios necesarios
+# 2. Probar instalación en proyecto limpio
+mkdir test-install && cd test-install
+npm init -y
+npm install nwinread@latest
+
+# 3. Verificar funcionamiento
+node -e "const n=require('nwinread'); console.log('✅ Funciona:', n.readEvents('System',0,0,1).records.length)"
+```
+
+## 🛠️ Comandos de Desarrollo
+
+### **Para Desarrollo Diario:**
+```bash
+npm run build        # Compilación local tradicional
+npm test            # Probar funcionamiento
+npm run verify      # Verificar configuración completa
+```
+
+### **Para Release Local (Opcional):**
+```bash
+npm run prebuildify  # Generar binario para plataforma actual
+npm run prebuild     # Alias para prebuildify
+npm pack            # Crear tarball para pruebas
+```
+
+### **Para Release de Producción:**
+```bash
+npm version [patch|minor|major]  # Incrementa versión + prebuild
+git push origin --tags           # Dispara CI/CD
+```
+
+## 🔍 Estructura de Binarios Generados
+
+```
+prebuilds/
+├── win32-x64/
+│   └── nwinread.node     # Windows 64-bit (generado localmente)
+│
+# Después del CI/CD automático:
+├── win32-x64/
+│   ├── nwinread.node.16   # Para Node.js 16.x
+│   ├── nwinread.node.18   # Para Node.js 18.x  
+│   ├── nwinread.node.20   # Para Node.js 20.x
+│   └── nwinread.node.22   # Para Node.js 22.x
+└── win32-arm64/
+    ├── nwinread.node.16   # ARM64 builds
+    ├── nwinread.node.18
+    ├── nwinread.node.20
+    └── nwinread.node.22
+```
+
+## ⚠️ **Solución de Problemas Comunes**
+
+### **❌ "npm install sigue compilando"**
+```bash
+# Verificar configuración:
+npm run verify
+
+# Problemas comunes:
+- ✅ Asegurar que existe `prebuilds/` con binarios
+- ✅ Verificar `"install": "node-gyp-build"` en package.json
+- ✅ Confirmar que no está `"gypfile": true` 
+```
+
+### **❌ "CI/CD no genera binarios"**
+```bash
+# Verificar:
+1. Push del tag: git push origin --tags
+2. Workflow habilitado en GitHub repo
+3. Secrets configurados (NPM_TOKEN si autoPublish)
+```
+
+### **❌ "Binario no compatible"**
+```bash
+# El usuario puede forzar compilación:
+npm rebuild nwinread
+
+# O solicitar soporte para su plataforma
+# agregando su combinación OS-ARCH al CI/CD
+```
    - Publica automáticamente a npm
 
 4. **Usuario Final**:

package/README.md

@@ -12,32 +12,43 @@ A native Node.js module for reading Windows event logs using the Windows Event L
 ## Requirements
 
 - Windows Vista/7/8/10/11 or Windows Server 2008/2012/2016/2019/2022  
-- Node.js (version 16 or higher)
+- **Node.js 16+** (recommended for precompiled binaries)
+- **Node.js 10-14** (requires local compilation)
 
-**Build requirements (only if compiling from source):**
+### 🐎 **Node.js Version Support:**
+
+| Node.js | Status | Installation |
+|---------|--------|-------------|
+| **16.x** | ✅ **LTS** | Instant (precompiled) |
+| **18.x** | ✅ **LTS** | Instant (precompiled) |
+| **20.x** | ✅ **LTS** | Instant (precompiled) |
+| **22.x** | ✅ **Current** | Instant (precompiled) |
+| 10-14 | ⚠️ **EOL** | Requires build tools |
+
+**Build requirements (only for Node.js 10-14 or development):**
 - Visual Studio Build Tools or Visual Studio Community
 - Python (for node-gyp)
 
 ## Installation
 
-### From npm (recommended - includes precompiled binaries)
+### 🚀 **Quick Install (Recommended)**
 
 ```bash
 npm install nwinread
 ```
 
-### From source (for development)
+**✅ For Node.js 16+**: Installs instantly using precompiled binaries  
+**⚠️ For Node.js 10-14**: Automatically compiles from source (requires build tools)
+
+### 🔧 **Development Install**
 
 ```bash
 git clone https://github.com/solzimer/nwinread.git
 cd nwinread
 npm install
 npm run build
+npm test
 ```
-
-### Manual compilation
-
-```bash
 # Install dependencies
 npm install
 
@@ -131,6 +142,31 @@ const noFilter = nwinread.readEvents('System', nwinread.START_MODE.BEGINNING, 0,
 - **4624**: Successful account logon (Security log)
 - **4625**: Failed account logon (Security log)
 
+## Development & Release Process
+
+### 🏗️ **For Contributors/Maintainers:**
+
+```bash
+# Development workflow
+npm run build       # Compile locally
+npm run prebuildify # Generate precompiled binary for current platform
+npm test           # Run tests
+npm run verify     # Verify complete setup
+
+# Release new version
+npm version [patch|minor|major]  # Auto-generates prebuilds
+git push origin --tags           # Triggers CI/CD for multi-platform builds
+```
+
+### 📦 **Publishing Process:**
+
+1. **Local Testing**: `npm test && npm run verify`
+2. **Version Bump**: `npm version patch` (auto-runs prebuildify)
+3. **Push Release**: `git push origin --tags`
+4. **CI/CD Magic**: GitHub Actions builds for all platforms & publishes automatically
+
+**Note**: The `prepublishOnly` script ensures binaries are generated before any npm publish.
+
 ## Testing
 
 ```bash
@@ -139,9 +175,23 @@ npm test
 
 ## Troubleshooting
 
-1. **Compilation error**: Make sure you have Visual Studio Build Tools installed
-2. **Permission error**: Some logs require administrator privileges
-3. **Channel not found**: Verify that the channel name is correct
+### **Installation Issues**
+
+1. **"Still compiling on install"**: 
+   - ✅ Update to Node.js 16+ for precompiled binaries
+   - ✅ Check `npm ls nwinread` shows correct version
+   - ✅ Try `npm cache clean --force && npm install`
+
+2. **"Module not found"**: 
+   - ✅ Ensure Windows platform (module is Windows-only)
+   - ✅ Try `npm rebuild nwinread`
+   - ✅ Check administrator privileges if needed
+
+### **Runtime Issues**
+
+3. **Permission error**: Some logs require administrator privileges
+4. **Channel not found**: Verify that the channel name is correct  
+5. **Old Node.js**: Update to Node.js 16+ for best experience
 
 ## Common channels
 

package/index.js

@@ -1,28 +1,4 @@
-const { join } = require('path');
-
-let native;
-
-// Intentar cargar el binario precompilado
-try {
-  // Detectar la plataforma y arquitectura
-  const platform = process.platform;
-  const arch = process.arch;
-  
-  // Intentar cargar binario precompilado (prebuildify naming convention)
-  const prebuiltPath = join(__dirname, 'prebuilds', `${platform}-${arch}`, 'nwinread.node');
-  native = require(prebuiltPath);
-  
-} catch (error) {
-  // Fallback al binario compilado localmente
-  try {
-    native = require('./build/Release/eventlog.node');
-  } catch (buildError) {
-    throw new Error(
-      `Failed to load native module. Please run 'npm run build' or install from npm: ${buildError.message}\n` +
-      `Original prebuild error: ${error.message}`
-    );
-  }
-}
+const native = require('node-gyp-build')(__dirname);
 
 const START_MODE = {
   BEGINNING: 0,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nwinread",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "main": "index.js",
   "scripts": {
     "build": "node-gyp configure && node-gyp build",
@@ -11,7 +11,8 @@
     "prebuildify-cross": "prebuildify-cross",
     "prebuild": "npm run prebuildify",
     "verify": "node scripts/verify-setup.js",
-    "prepublishOnly": "npm run prebuild"
+    "prepublishOnly": "npm run prebuild",
+    "install": "node-gyp-build"
   },
   "author": "solzimer",
   "license": "MIT",
@@ -30,10 +31,11 @@
   "devDependencies": {
     "node-gyp": "^10.0.0",
     "prebuildify": "^6.0.0",
-    "prebuildify-cross": "^5.0.0"
+    "prebuildify-cross": "^5.0.0",
+    "node-addon-api": "^8.0.0"
   },
   "dependencies": {
-    "node-addon-api": "^8.0.0"
+    "node-gyp-build": "^4.8.0"
   },
   "binary": {
     "napi_versions": [
@@ -45,6 +47,5 @@
       8,
       9
     ]
-  },
-  "gypfile": true
+  }
 }

package/scripts/verify-setup.js

@@ -35,7 +35,8 @@ try {
   
   console.log('✅ N-API configurado:', pkg.binary?.napi_versions ? 'Sí' : 'No');
   console.log('✅ Scripts prebuildify:', pkg.scripts?.prebuildify ? 'Sí' : 'No'); 
-  console.log('✅ node-addon-api:', pkg.dependencies?.['node-addon-api'] ? 'Sí' : 'No');
+  console.log('✅ node-gyp-build:', pkg.dependencies?.['node-gyp-build'] ? 'Sí' : 'No');
+  console.log('✅ node-addon-api:', (pkg.dependencies?.['node-addon-api'] || pkg.devDependencies?.['node-addon-api']) ? 'Sí' : 'No');
   
 } catch (e) {
   console.log('❌ Error leyendo package.json:', e.message);