ai-first-cli 1.2.1 → 1.2.3

package/ANALISIS_MEJORAS.md

@@ -0,0 +1,327 @@
+# 📋 ANÁLISIS COMPLETO DE MEJORAS - ai-first-cli
+## Fecha: 2026-03-17
+## Versión analizada: 1.1.5
+
+---
+
+## ✅ PUNTO 1 COMPLETADO: Release v1.1.5
+
+- ✅ Versión actualizada a 1.1.5
+- ✅ CHANGELOG.md actualizado
+- ✅ BUGS.md actualizado con nuevos issues
+- ✅ Build exitoso
+- ✅ Commit realizado (f983ba8)
+- ✅ Push a GitHub completado
+- ⏳ NPM publish (pendiente de confirmación del usuario)
+
+**Commit:** https://github.com/julianperezpesce/ai-first/commit/f983ba8
+
+---
+
+## 🔍 ANÁLISIS DE PROBLEMAS Y MEJORAS IDENTIFICADAS
+
+### 1. COBERTURA DE TESTING (Alta Prioridad)
+
+**Estado actual:**
+- ✅ 5 proyectos de test funcionando (Express, NestJS, Python CLI, React, Salesforce)
+- ❌ 11+ frameworks sin testing
+
+**Frameworks soportados pero NO testeados:**
+| Framework | Tipo | Prioridad |
+|-----------|------|-----------|
+| Laravel | PHP Web | Alta |
+| Django | Python Web | Alta |
+| Flask/FastAPI | Python API | Alta |
+| Rails | Ruby Web | Media |
+| Spring Boot | Java Enterprise | Media |
+| ASP.NET Core | C# Web | Media |
+| Blazor | .NET Frontend | Baja |
+| Phoenix | Elixir Web | Baja |
+| FastAPI | Python API | Alta |
+| Ruby | Ruby general | Baja |
+
+**Impacto:** Los usuarios de estos frameworks pueden encontrar errores no detectados.
+
+**Solución recomendada:**
+1. Crear un test project para cada framework soportado
+2. Implementar test automatizados que validen:
+   - Generación correcta de símbolos
+   - Detección de entrypoints
+   - Extracción de dependencias
+   - Generación de features/flows
+3. Ejecutar tests en CI/CD antes de cada release
+
+---
+
+### 2. ARCHIVOS DUPLICADOS (Media Prioridad)
+
+**Problema detectado:**
+En `ai/` se generan archivos duplicados con diferentes convenciones:
+
+```
+ai/
+├── repo-map.json      ← kebab-case
+├── repo_map.json      ← snake_case
+├── repo_map.md        ← snake_case
+├── module-graph.json  ← kebab-case
+├── symbol-graph.json  ← kebab-case
+└── ...
+```
+
+**Archivos duplicados encontrados:**
+1. `repo-map.json` vs `repo_map.json`
+2. Posiblemente otros casos similares
+
+**Impacto:**
+- Confusión para usuarios (¿cuál usar?)
+- Doble espacio en disco
+- Inconsistencia percibida
+
+**Solución recomendada:**
+1. Elegir UNA convención (recomendado: snake_case)
+2. Mantener solo `repo_map.json`
+3. Eliminar `repo-map.json` o marcarlo como deprecated
+4. Actualizar toda la documentación
+
+**Archivos a modificar:**
+- `src/commands/ai-first.ts` (líneas que generan repo-map)
+- `src/core/aiContextGenerator.ts`
+- `src/core/ccp.ts`
+
+---
+
+### 3. INCONSISTENCIAS DE NOMENCLATURA (Media Prioridad)
+
+**Problema detectado:**
+Mezcla de convenciones en archivos generados:
+
+| Archivo | Convención Actual | Convención Recomendada |
+|---------|-------------------|------------------------|
+| `repo-map.json` | kebab-case | `repo_map.json` |
+| `module-graph.json` | kebab-case | `module_graph.json` |
+| `symbol-graph.json` | kebab-case | `symbol_graph.json` |
+| `knowledge-graph.json` | kebab-case | `knowledge_graph.json` |
+| `symbol-references.json` | kebab-case | `symbol_references.json` |
+| `ai_context.md` | snake_case | ✅ Correcto |
+| `tech_stack.md` | snake_case | ✅ Correcto |
+| `repo_map.md` | snake_case | ✅ Correcto |
+
+**Impacto:**
+- Difícil de recordar nombres
+- Inconsistencia visual
+- No sigue estándares de Node.js (que usa snake_case o camelCase)
+
+**Solución recomendada:**
+1. Estandarizar TODO a snake_case
+2. Crear función helper `toSnakeCase()` para consistencia
+3. Actualizar todos los generadores de archivos
+4. Agregar test que valide convenciones
+
+**Ejemplo de cambio:**
+```typescript
+// Antes
+const outputFile = path.join(outputPath, 'module-graph.json');
+
+// Después  
+const outputFile = path.join(outputPath, 'module_graph.json');
+```
+
+---
+
+### 4. ORGANIZACIÓN DE CARPETA ai/ (Alta Prioridad)
+
+**Problema detectado:**
+La carpeta `ai/` en el repositorio contiene archivos que NO son generados por el CLI:
+
+```
+ai/ (en el repo, no generado)
+├── ai_context.md          ← Generado por CLI ✅
+├── ai_rules.md            ← Generado por CLI ✅
+├── cache.json             ← Cache (temporal) ⚠️
+├── embeddings.json        ← Muy grande (706KB) ⚠️
+├── git/                   ← Datos git temporales ⚠️
+├── hierarchy.json         ← Temporal ⚠️
+├── index-state.json       ← Estado interno ⚠️
+└── ...
+```
+
+**Problemas:**
+1. Los usuarios no saben qué archivos versionar
+2. Archivos temporales/cache ocupan espacio
+3. Mezcla de archivos de ejemplo con archivos reales
+4. Los test projects tienen archivos `ai/` versionados
+
+**Solución recomendada:**
+
+#### Opción A: Estructura limpia (Recomendada)
+```
+ai/
+├── ai_context.md          ← ✅ Mantener (principal)
+├── ai_rules.md            ← ✅ Mantener (reglas)
+├── architecture.md        ← ✅ Mantener
+├── conventions.md         ← ✅ Mantener
+├── dependencies.json      ← ✅ Mantener
+├── entrypoints.md         ← ✅ Mantener
+├── repo_map.md            ← ✅ Mantener
+├── symbols.json           ← ✅ Mantener
+├── tech_stack.md          ← ✅ Mantener
+├── context/               ← ✅ Mantener (features, flows)
+├── graph/                 ← ✅ Mantener (graphs estáticos)
+├── .cache/                ← 🆕 Nuevo (archivos temporales)
+│   ├── cache.json
+│   ├── index-state.json
+│   └── embeddings.json
+└── .git/                  ← 🆕 Mover desde raíz
+    └── ...
+```
+
+#### Opción B: Separación completa
+```
+repo/
+├── ai/                    ← Solo archivos esenciales
+│   ├── ai_context.md
+│   ├── symbols.json
+│   └── ...
+├── .ai-cache/             ← Temporales (en .gitignore)
+│   └── ...
+└── .ai-git/               ← Datos git (en .gitignore)
+    └── ...
+```
+
+**Archivos a modificar:**
+- `.gitignore` (agregar `ai/.cache/`, `ai/.git/`)
+- `src/commands/ai-first.ts` (cambiar rutas de salida)
+- `src/core/indexer.ts` (cambiar ruta de index.db)
+- Documentación
+
+---
+
+### 5. MANEJO DE ERRORES GIT (Baja Prioridad)
+
+**Problema actual:**
+```bash
+$ ai-first git --root test-projects/express-api
+❌ Not a git repository
+EXIT_CODE: 1
+```
+
+**Mejora recomendada:**
+```bash
+$ ai-first git --root test-projects/express-api
+⚠️  No git repository found in test-projects/express-api
+
+💡 To enable git analysis:
+   1. cd test-projects/express-api
+   2. git init
+   3. git add .
+   4. git commit -m "Initial commit"
+
+📚 Learn more: https://ai-first-cli.netlify.app/docs/git-command
+```
+
+**Beneficios:**
+- Mejor UX para nuevos usuarios
+- Reduce tickets de soporte
+- Educación inline
+
+---
+
+### 6. MEJORAS ADICIONALES IDENTIFICADAS
+
+#### 6.1 Validación de archivos generados
+**Problema:** No hay validación automática de que los archivos generados sean válidos.
+
+**Solución:** Agregar validación:
+```typescript
+// Después de generar JSON
+const validateJson = (content: string) => {
+  try {
+    JSON.parse(content);
+    return true;
+  } catch {
+    return false;
+  }
+};
+```
+
+#### 6.2 Tamaño de archivos
+**Problema:** `embeddings.json` puede ser muy grande (706KB en ejemplo).
+
+**Solución:** 
+- Agregar compresión opcional
+- O dividir en chunks
+- O guardar en SQLite en lugar de JSON
+
+#### 6.3 Documentación de archivos generados
+**Falta:** Tabla clara que explique cada archivo generado.
+
+**Solución:** Crear `docs/generated-files.md`:
+| Archivo | Propósito | ¿Versionar? | Tamaño típico |
+|---------|-----------|-------------|---------------|
+| ai_context.md | Contexto principal para AI | Sí | ~2KB |
+| symbols.json | Símbolos del proyecto | Sí | ~30KB |
+| index.db | Base de datos SQLite | Opcional | ~45KB |
+| cache.json | Cache temporal | No | Variable |
+
+#### 6.4 Cleanup automático
+**Problema:** Archivos viejos no se limpian automáticamente.
+
+**Solución:** Agregar `ai-first clean`:
+```bash
+ai-first clean              # Limpiar cache
+ai-first clean --all        # Limpiar todo excepto esenciales
+ai-first clean --cache      # Solo cache
+```
+
+#### 6.5 Configuración global
+**Falta:** Archivo de configuración para defaults.
+
+**Solución:** Soportar `ai-first.config.json`:
+```json
+{
+  "outputDir": "./ai",
+  "exclude": ["*.test.js", "node_modules"],
+  "cacheEnabled": true,
+  "maxFileSize": "1MB"
+}
+```
+
+---
+
+## 📊 RESUMEN DE PRIORIDADES
+
+| # | Issue | Prioridad | Esfuerzo | Impacto |
+|---|-------|-----------|----------|---------|
+| 1 | Testing de frameworks | 🔴 Alta | Alto | Alto |
+| 2 | Organización de ai/ | 🔴 Alta | Medio | Alto |
+| 3 | Archivos duplicados | 🟡 Media | Bajo | Medio |
+| 4 | Inconsistencias de nombres | 🟡 Media | Medio | Medio |
+| 5 | Manejo de errores git | 🟢 Baja | Bajo | Bajo |
+| 6 | Validación de archivos | 🟡 Media | Medio | Medio |
+| 7 | Documentación de archivos | 🟢 Baja | Bajo | Medio |
+| 8 | Cleanup automático | 🟢 Baja | Medio | Bajo |
+| 9 | Configuración global | 🟢 Baja | Medio | Medio |
+
+---
+
+## 🎯 RECOMENDACIONES INMEDIATAS
+
+### Para v1.1.6 (Próximo release):
+1. ✅ Testing completo de Laravel y Django
+2. ✅ Documentar estructura de ai/ claramente
+3. ✅ Agregar mensaje amigable para error de git
+
+### Para v1.2.0 (Release mayor):
+1. Reorganizar estructura de ai/ (breaking change)
+2. Consolidar archivos duplicados (breaking change)
+3. Estandarizar nomenclatura (breaking change)
+
+### Para v2.0.0 (Futuro):
+1. Sistema de plugins
+2. Configuración global
+3. UI web para visualizar graphs
+
+---
+
+*Análisis completado: 2026-03-17*
+*Issues registrados en: BUGS.md (sección "Nuevos Issues Identificados")*

package/README.es.md

@@ -6,8 +6,8 @@
   <a href="https://github.com/julianperezpesce/ai-first/stargazers">
     <img src="https://img.shields.io/github/stars/julianperezpesce/ai-first?style=flat&color=ffd700" alt="Stars">
   </a>
-  <a href="https://www.npmjs.com/package/ai-first">
-    <img src="https://img.shields.io/npm/dt/ai-first?color=blue" alt="NPM Downloads">
+  <a href="https://www.npmjs.com/package/ai-first-cli">
+    <img src="https://img.shields.io/npm/dt/ai-first-cli?color=blue" alt="NPM Downloads">
   </a>
   <a href="https://opensource.org/licenses/MIT">
     <img src="https://img.shields.io/badge/License-MIT-green.svg" alt="License">
@@ -19,11 +19,50 @@
 
 > **Dale superpoderes a tu asistente de código IA.** Genera contexto instantáneo del proyecto para que los agentes IA comprendan tu código en segundos, no en minutos.
 
-<!-- START FIRST 10 SECONDS VALUE -->
+---
+
+## 📋 Tabla de Contenidos
+
+- [Comandos](#-referencia-de-comandos)
+- [Inicio Rápido](#-inicio-rápido)
+- [Instalación](#-instalación)
+- [Casos de Uso](#-casos-de-uso)
+- [Benchmark](#-benchmark)
+- [Cómo Funciona](#-cómo-funciona)
+- [Archivos Generados](#-archivos-generados)
+- [Agentes IA](#-agentes-ia-soportados)
+- [Roadmap](#-roadmap)
+- [Contribuir](#-para-contribuidores)
+
+---
+
+## ⚡ Referencia de Comandos
+
+| Comando | Descripción |
+|---------|-------------|
+| `af init` | Genera todos los archivos de contexto (símbolos, dependencias, arquitectura, etc.) |
+| `af index` | Crea base de datos SQLite para consultas rápidas de símbolos |
+| `af update` | Actualiza incrementally el contexto cuando archivos cambian |
+| `af watch` | Observa cambios y actualiza el índice automáticamente |
+| `af context` | Extrae contexto alrededor de un símbolo o función específica |
+| `af explore` | Explora dependencias de módulos interactivamente |
+| `af map` | Genera mapa del repositorio con todas las relaciones |
+| `af doctor` | Verifica salud del repositorio y preparación para IA |
+| `af query` | Consulta el índice (símbolos, imports, exports, stats) |
+| `af adapters` | Lista adaptadores de lenguajes/frameworks soportados |
+| `af git` | Muestra actividad reciente de git y archivos cambiados |
+| `af graph` | Muestra visualización del grafo de conocimiento |
+| `af --completions` | Genera script de autocompletado para shell |
+
+> **Nota:** Todos los comandos funcionan con `af` (recomendado) o `ai-first` (legacy).
+
+---
+
 ## ⚡ En 10 Segundos
 
 ```
-$ npx ai-first init
+$ npm install -g ai-first-cli
+$ af init
 ✅ Generated ai-context/ai_context.md (0.3s)
 ✅ Generated ai-context/symbols.json (0.1s)  
 ✅ Generated ai-context/dependencies.json (0.1s)
@@ -33,7 +72,6 @@ $ npx ai-first init
 ```
 
 **Resultado:** La IA comprende tu proyecto en ~500 tokens en lugar de 50,000.
-<!-- END FIRST 10 SECONDS VALUE -->
 
 ---
 
@@ -42,69 +80,54 @@ $ npx ai-first init
 Inicializa AI-First en tu repositorio:
 
 ```
-ai-first init
+af init
 ```
 
 Indexa el repositorio para que los agentes de IA puedan entender el código:
 
 ```
-ai-first index
-```
-
-Genera un mapa de arquitectura del repositorio:
-
-```
-ai-first summarize
+af index
 ```
 
 * `init` genera 11 archivos de contexto con metadatos del proyecto
 * `index` crea una base de datos SQLite para consultas rápidas de símbolos
-* `summarize` crea resúmenes jerárquicos para navegación IA
 
 ---
 
-## ❓ Por qué AI-First?
-
-Los asistentes de código IA a menudo tienen dificultades con repositorios grandes.
-
-**Problemas comunes:**
-
-* ventanas de contexto limitadas
-* falta de conocimiento arquitectónico
-* dificultad para navegar bases de código grandes
-* relaciones perdidas entre módulos
+## 📦 Instalación
 
-AI-First resuelve esto creando una capa de inteligencia del repositorio.
+### Requisitos
+- Node.js 18+ (para indexación semántica opcional)
 
-Esto permite a los agentes IA:
+### Instalar
 
-* entender la estructura del proyecto
-* recuperar código relevante
-* navegar repositorios grandes
-* mantener contexto arquitectónico
+```bash
+# Instalar globalmente (recomendado)
+npm install -g ai-first-cli
 
----
+# Ahora puedes usar el comando 'af'
+af init
+af index
+af doctor
+```
 
-## 🚀 ¿Por qué ai-first?
+### Otros Métodos de Instalación
 
-| Antes de ai-first | Después de ai-first |
-|-------------------|---------------------|
-| La IA lee 500+ archivos para entender el proyecto | La IA lee 1 archivo con contexto completo |
-| $5+ por proyecto en costos de API | ~$0.05 por proyecto |
-| 30+ segundos para que la IA "se caliente" | Comprensión instantánea |
-| La IA pierde convenciones y patrones | La IA conoce tu arquitectura |
+```bash
+# Homebrew (macOS/Linux)
+brew tap julianperezpesce/tap
+brew install ai-first-cli
 
----
+# Script de instalación (Linux/macOS/WSL)
+curl -fsSL https://raw.githubusercontent.com/julianperezpesce/ai-first/master/install.sh | bash
+```
 
-## 📦 Instalación
+### Autocompletado de Shell
 
 ```bash
-# Inicio rápido (sin instalación)
-npx ai-first init
-
-# O instalar globalmente
-npm install -g ai-first
-ai-first init
+# Para bash
+af --completions > /usr/local/etc/bash_completion.d/af.bash
+source /usr/local/etc/bash_completion.d/af.bash
 ```
 
 ---
@@ -113,19 +136,19 @@ ai-first init
 
 ### 1. Agentes de Código IA (OpenCode, Cursor, Claude Code)
 ```bash
-ai-first init
+af init
 # Luego pregunta a la IA: "Lee ai-context/ai_context.md y ayúdame a agregar una característica"
 ```
 
 ### 2. Incorporación de Nuevos Desarrolladores
 ```bash
-ai-first init
+af init
 # El nuevo desarrollador lee ai-context/ai_context.md → comprende el proyecto en 2 minutos
 ```
 
 ### 3. Documentación del Proyecto
 ```bash
-ai-first init
+af init
 # Documentación automática instantánea siempre actualizada
 ```
 
@@ -146,7 +169,7 @@ Resultado: Código roto, tokens desperdiciados
 ### Después: IA Ilustrada
 
 ```
-$ ai-first init
+$ af init
 
 Tú: "Lee ai-context/ai_context.md, luego agrega autenticación"
 IA: *lee 1 archivo (0.5s)*
@@ -243,22 +266,19 @@ ai-context/
 ├── repo_map.json      # Estructura legible por máquina
 ├── symbols.json       # Funciones/clases extraídas
 ├── dependencies.json  # Relaciones de imports
-├── architecture.md   # Patrón de arquitectura
+├── architecture.md    # Patrón de arquitectura
 ├── tech_stack.md      # Lenguajes y frameworks
 ├── entrypoints.md     # Puntos de entrada
 ├── conventions.md     # Convenciones de código
-├── index.db           # SQLite (con índice ai-first)
-│
-├── graph/             # Generado por `ai-first map`
-│   ├── module-graph.json   # Grafo de dependencias a nivel de módulo
-│   └── symbol-graph.json   # Relaciones a nivel de símbolo (calls, imports, etc.)
-│
-└── context/           # Generado por `ai-first init` o `map`
+├── index.db           # Índice SQLite (generado por `af index`)
+├── graph/             # Grafos de dependencias (generado por `af map`)
+│   ├── module-graph.json
+│   └── symbol-graph.json
+└── context/           # Contexto de negocio (generado por `af init`)
     ├── features/      # Features de negocio detectados
     │   └── <modulo>.json
     └── flows/         # Cadenas de ejecución de negocio
         └── <flujo>.json
-└── index.db           # SQLite (con índice ai-first)
 ```
 
 ---
@@ -279,16 +299,16 @@ ai-context/
 
 ```bash
 # Generar contexto
-ai-first init
+af init
 
 # Generar índice SQLite
-ai-first index
+af index
 
 # Directorio de salida personalizado
-ai-first init --output ./docs/ai
+af init --output ./docs/ai
 
 # Directorio raíz personalizado
-ai-first init --root ./my-project
+af init --root ./my-project
 ```
 
 ---
@@ -299,14 +319,14 @@ CCP (Context Control Packs) te permite crear contextos reutilizables y específi
 
 ### Cómo Funciona
 
-1. **Generar Módulos de Contexto**: `ai-first init` crea módulos en `ai-context/context/`
+1. **Generar Módulos de Contexto**: `af init` crea módulos en `ai-context/context/`
 2. **Crear un CCP**: Define qué módulos incluir para una tarea específica
 3. **Usar en IA**: Referencia el CCP al trabajar con agentes de IA
 
 ### Ejemplo
 
 ```bash
-ai-first ccp create tarea-auth --include repo,auth,api --description "Trabajo en autenticación"
+af ccp create tarea-auth --include repo,auth,api --description "Trabajo en autenticación"
 ```
 
 ---
@@ -353,13 +373,13 @@ Los flows representan cadenas de ejecución de negocio desde entrypoints.
 }
 ```
 
-**Generado por:** `ai-first init` o `ai-first map`
+**Generado por:** `af init` o `af map`
 
 ---
 
 ## 🤖 Soporte Android/Kotlin
 
-ai-first detecta e indexa automáticamente proyectos Android/Kotlin:
+af detecta e indexa automáticamente proyectos Android/Kotlin:
 
 - **Detección de lenguaje**: Kotlin (.kt)
 - **Detección de framework**: Android (vía build.gradle, AndroidManifest.xml)
@@ -388,19 +408,23 @@ ai-first detecta e indexa automáticamente proyectos Android/Kotlin:
 - Soporte para parsers PHP y Ruby agregado
 - 11 adapters funcionando (100% cobertura)
 
-### Phase 3 (Planificado)
-- [ ] Indexación semántica mejorada
-- [ ] Sistema de plugins para analizadores custom
-- [ ] Soporte Scala
-- [ ] Soporte de archivo de configuración (`ai-first.config.json`)
-- [ ] Sistema de reglas/plugins custom
-- [ ] Plantillas de integración CI/CD
+### Phase 3 ✅ (Completado)
+- Indexación semántica mejorada
+- Soporte PHP y Ruby (proyectos de prueba Laravel y Rails)
+- Soporte de archivo de configuración (`ai-first.config.json`)
+- Sistema de reglas/plugins custom
+- Plantillas de integración CI/CD
 
-### Phase 4 (Futuro)
-- [ ] Integración con Git (analizar cambios recientes)
-- [ ] Contexto aware de diff (qué cambió desde última ejecución)
-- [ ] Modo interactivo
-- [ ] Extensión de VS Code
+### Phase 4 ✅ (Completado)
+- Integración con Git (analizar cambios recientes)
+- Contexto aware de diff (qué cambió desde última ejecución)
+- Modo interactivo
+- Índice SQLite para consultas rápidas de símbolos
+
+### Phase 5 ✅ (Completado)
+- Arquitectura: `ai/` → `ai-context/`
+- Rendimiento: embeddings a SQLite
+- Documentación: mejoras comprehensivas del README
 
 ---
 
@@ -443,7 +467,7 @@ Ver [docs/architecture.md](./docs/architecture.md) para arquitectura interna.
 
 ## 🤖 Soporte Android/Kotlin
 
-ai-first detecta e indexa automáticamente proyectos Android/Kotlin:
+af detecta e indexa automáticamente proyectos Android/Kotlin:
 
 - **Detección de lenguaje**: Kotlin (.kt)
 - **Detección de framework**: Android (vía build.gradle, AndroidManifest.xml)
@@ -465,5 +489,3 @@ ai-first detecta e indexa automáticamente proyectos Android/Kotlin:
 ## 📄 Licencia
 
 MIT © [Julian Perez Pesce](https://github.com/julianperezpesce)
-
-MIT © [Julian Perez Pesce](https://github.com/julianperezpesce)