@helicondev/zora-code/README.md

Privacy-focused AI CLI tool for developers. Fork of Qwen-Code with custom commands, configurable rules, and automatic ZORA.md generation for enhanced AI context and project understanding.

# Zora Code

![Captura de pantalla de Zora Code](https://i.ibb.co/4ZqNzkLB/zora.png)

Zora Code es una herramienta de línea de comandos con IA que te ayuda a entender, editar y automatizar tareas en tu código. Está optimizada para modelos [Qwen3-Coder](https://github.com/QwenLM/Qwen3-Coder) y ofrece una experiencia mejorada para desarrolladores.

## Características principales

- **Comprensión y edición de código** - Consulta y edita bases de código grandes más allá de los límites tradicionales de ventana de contexto
- **Automatización de flujos de trabajo** - Automatiza tareas operativas como manejo de pull requests y rebases complejos
- **Análisis de proyectos** - Analiza y documenta automáticamente la estructura del proyecto con el comando `/init`
- **Reglas y comandos personalizados** - Define comportamientos de IA y atajos específicos para tu proyecto
- **Seguridad y privacidad mejoradas** - Almacenamiento seguro de credenciales y telemetría completamente desactivada

## Capacidades avanzadas de Zora Code

### Herramientas de análisis y búsqueda
- **Búsqueda inteligente** - Busca patrones, funciones, clases y variables en toda tu base de código
- **Análisis de dependencias** - Identifica y mapea dependencias entre archivos y módulos
- **Navegación de código** - Encuentra definiciones, usos y referencias de elementos del código
- **Análisis estático** - Detecta patrones, anti-patrones y posibles mejoras

### Herramientas de desarrollo
- **Ejecución de comandos** - Ejecuta scripts, tests, builds y comandos del sistema
- **Gestión de archivos** - Crear, mover, copiar y organizar archivos y directorios
- **Control de versiones** - Integración completa con Git para commits, branches, merges y más
- **Debugging** - Asistencia en identificación y resolución de errores

### Generación y transformación de código
- **Refactoring inteligente** - Reestructura código manteniendo funcionalidad
- **Generación de tests** - Crea tests unitarios y de integración automáticamente
- **Documentación automática** - Genera documentación de APIs, funciones y módulos
- **Migración de código** - Convierte entre lenguajes, frameworks y versiones

### Automatización de tareas
- **CI/CD** - Configuración y optimización de pipelines de integración continua
- **Gestión de dependencias** - Actualización y mantenimiento de paquetes
- **Optimización de rendimiento** - Análisis y mejoras de performance
- **Configuración de herramientas** - Setup de linters, formatters y herramientas de desarrollo

## Instalación

### Requisitos previos

Asegúrate de tener [Node.js versión 20](https://nodejs.org/en/download) o superior instalado.

### Instalación desde npm

```bash
npm install -g @helicondev/zora-code
zora --version
```

Luego ejecuta desde cualquier lugar:

```bash
zora
```

## Configuración

Zora Code funciona con OpenRouter para acceder a modelos de IA. Sigue estos pasos para configurarlo:

1. **Crea una API Key en [OpenRouter](https://openrouter.ai)**

2. **Configura las variables de entorno necesarias:**

```bash
export OPENAI_API_KEY="TU_API_KEY"
export OPENAI_BASE_URL="https://openrouter.ai/api/v1"
export OPENAI_MODEL="qwen/qwen3-coder"
```

Para configurar múltiples modelos y poder cambiar entre ellos durante la sesión:

```bash
export OPENAI_MODEL="qwen/qwen3-coder,qwen/qwen3-235b-a22b"
```

Alternativamente, puedes configurar estas variables en un archivo `.env` en el directorio raíz de tu proyecto:

```env
OPENAI_API_KEY=TU_API_KEY
OPENAI_BASE_URL=https://openrouter.ai/api/v1
OPENAI_MODEL=qwen/qwen3-235b-a22b:free

# Para múltiples modelos:
OPENAI_MODEL=qwen/qwen3-235b-a22b:free,qwen/qwen3-coder:free,gpt-4,claude-3-sonnet
```

### Cambio de modelo durante la sesión

Una vez configurados múltiples modelos, puedes cambiar entre ellos usando el comando `/model`:

```bash
# Ver modelos disponibles y cambiar interactivamente
> /model

# Cambiar directamente a un modelo específico
> /model gpt-4
```

## Uso básico

### Inicialización de proyectos

Para comenzar a usar Zora Code en tu proyecto, ejecuta el comando `/init`:

```sh
cd tu-proyecto/
zora
> /init
```

Este comando analiza automáticamente tu proyecto y genera un archivo `ZORA.md` con información sobre:
- Lenguajes de programación y frameworks
- Estructura del proyecto
- Dependencias y sistemas de compilación
- Estrategias de prueba
- Información del repositorio Git

### Exploración y análisis de código

Una vez inicializado, puedes hacer preguntas complejas sobre tu código:

```sh
zora
> Describe las partes principales de la arquitectura de este sistema
> ¿Qué hace esta función y cómo se relaciona con el resto del código?
> ¿Dónde se define esta variable y dónde se usa?
> Encuentra todos los componentes que usan esta API
> Analiza las dependencias de este módulo
> Busca patrones de código duplicado en el proyecto
```

### Edición y transformación de código

Puedes pedirle a Zora Code que edite tu código de formas sofisticadas:

```sh
zora
> Refactoriza esta función para mejorar la legibilidad y performance
> Añade comentarios explicativos y documentación JSDoc a este archivo
> Convierte este código JavaScript a TypeScript con tipos estrictos
> Migra este componente de clase a hook funcional de React
> Optimiza esta consulta SQL para mejor rendimiento
> Implementa manejo de errores robusto en esta función
```

### Automatización y tareas avanzadas

Zora Code puede automatizar tareas complejas de desarrollo:

```sh
zora
> Ejecuta los tests y arregla cualquier falla que encuentres
> Configura un pipeline de CI/CD para este proyecto
> Actualiza todas las dependencias y resuelve conflictos
> Genera tests unitarios para toda la carpeta components/
> Crea documentación API completa para este backend
> Optimiza el bundle size de esta aplicación React
```

## Personalización

Zora Code permite personalizar su comportamiento mediante reglas y comandos definidos en el directorio `.zora` de tu proyecto.

### Reglas personalizadas

Las reglas son archivos markdown en `.zora/rules/` que definen estándares de codificación y comportamientos específicos para tu proyecto. Por ejemplo:

```markdown
# Pautas de estilo de código

Este proyecto sigue convenciones estrictas de estilo de código.

## Principios generales
1. Usa sangría consistente (2 espacios)
2. Usa camelCase para nombres de variables y funciones
3. Siempre usa const o let en lugar de var
```

### Comandos personalizados

Los comandos son archivos markdown en `.zora/commands/` que crean atajos para tareas comunes. Por ejemplo:

```markdown
# Revisión de código
Realiza una revisión de código exhaustiva.

## Uso
/review [ruta_al_archivo]

## Plantilla
Por favor revisa el siguiente código en busca de:
1. Mejores prácticas
2. Posibles errores
3. Oportunidades de optimización

{{input}}
```

Para usar estos comandos:

```sh
# Configura reglas y comandos personalizados
mkdir -p .zora/rules .zora/commands

# Usa comandos personalizados
zora
> /review src/components/Button.tsx
```

## Comandos especiales disponibles

Zora Code incluye comandos especiales que puedes usar con la sintaxis `/comando`:

### Comandos de análisis
- `/init` - Analiza e inicializa un proyecto, creando documentación automática
- `/search [término]` - Búsqueda avanzada en toda la base de código
- `/analyze` - Análisis profundo de la arquitectura del proyecto

### Comandos de desarrollo
- `/auto-commit` - Commit automático con IA
- `/add-rules` - Descarga reglas personalizadas desde repositorios GitHub
- `/add-commands` - Descarga comandos personalizados desde repositorios GitHub
- `/test` - Ejecuta y analiza tests del proyecto
- `/build` - Ejecuta el proceso de build y resuelve errores

### Comandos de gestión
- `/install [paquete]` - Instala y configura dependencias
- `/update` - Actualiza dependencias y resuelve conflictos
- `/deploy` - Asistencia en procesos de despliegue

## Funciones avanzadas

### Commit automático con IA

El comando `/auto-commit` automatiza el proceso de versionado y commit:

```text
> /auto-commit                   # Flujo completo (análisis + versionado + changelog + commit)
> /auto-commit --dry-run         # Vista previa sin ejecutar cambios
```

Este comando:
1. Analiza los cambios en el área de staging
2. Genera un mensaje de commit apropiado
3. Para proyectos con `package.json`, también actualiza la versión y el changelog

### Instalación de reglas personalizadas

El comando `/add-rules` permite descargar reglas desde repositorios GitHub:

```text
> /add-rules usuario/repositorio  # Descarga reglas desde GitHub
> /add-rules usuario/repo/path    # Descarga desde subdirectorio específico
```

### Instalación de comandos personalizados

El comando `/add-commands` permite descargar comandos personalizados desde repositorios GitHub:

```text
> /add-commands usuario/repositorio      # Descarga comandos desde GitHub
> /add-commands usuario/repo/commands    # Descarga desde subdirectorio específico
> /add-commands preview usuario/repo     # Vista previa antes de instalar
> /add-commands install usuario/repo     # Instala directamente sin previsualización
```

Los comandos personalizados se instalan en `.zora/commands/` y estarán disponibles como comandos `/nombre-comando` en tu próxima sesión.

### Automatización de tareas

Zora Code puede ayudarte a automatizar tareas comunes:

```text
> Convierte todas las imágenes en este directorio a formato PNG
> Analiza los commits de Git de los últimos 7 días
> Genera documentación para esta API
```

### Seguridad y privacidad

Zora Code prioriza la seguridad y privacidad con varias características incorporadas:

1. **Almacenamiento seguro de credenciales**: Las claves API y credenciales sensibles se almacenan en un almacén seguro en memoria
2. **Aislamiento de archivos**: El acceso a archivos se restringe al directorio del proyecto
3. **Telemetría desactivada**: Toda la telemetría está completamente desactivada por defecto
4. **Saneamiento del entorno**: Los entornos se sanean para prevenir la exposición de variables sensibles

Estas características aseguran que tu código y datos permanezcan seguros mientras usas Zora Code.

## Actualizaciones

Zora Code verifica automáticamente si hay nuevas versiones disponibles. Cuando haya una actualización, verás una notificación con instrucciones para actualizar.

Para actualizar manualmente:

```bash
# Verificar versión actual
zora --version

# Actualizar a la última versión
npm install -g @helicondev/zora-code@latest

# Verificar que la actualización fue exitosa
zora --version
```

## Reconocimientos

Este proyecto está basado en [Google Gemini CLI](https://github.com/google-gemini/gemini-cli). Reconocemos y apreciamos el excelente trabajo del equipo de Gemini CLI. Nuestra principal contribución se centra en adaptaciones a nivel de analizador para soportar mejor los modelos Qwen-Coder.

## Licencia

[LICENCIA](./LICENSE)