ai-first-cli 1.3.6 → 1.3.8

package/docs/planning/evaluator-v1.0.0/improvements_plan_2026-03-28.md

@@ -0,0 +1,237 @@
+# AI-First Evaluator - Plan de Mejoras
+
+**Template Version:** 1.0  
+**Evaluator Version:** 1.0.0  
+**Evaluation Date:** 2026-03-28  
+**Project:** express-api  
+**Current Score:** 3.88/5.0  
+**Status:** PASS
+
+---
+
+## Instrucciones de Uso
+
+Este documento es un TEMPLATE para registrar resultados de evaluación y planificar mejoras.
+
+### Para nuevas evaluaciones:
+1. Copiar este archivo como improvements_plan_YYYY-MM-DD.md
+2. Actualizar los campos marcados con [ACTUALIZAR]
+3. Documentar hallazgos específicos del proyecto
+4. Crear issues/tickets para acciones identificadas
+
+### Estructura del documento:
+- Resumen: Métricas principales y estado general
+- Hallazgos: Fortalezas y áreas de mejora
+- Plan de Acción: Tareas priorizadas con owners y deadlines
+- Seguimiento: Checklist de implementación
+
+---
+
+## Resumen Ejecutivo
+
+### Métricas Principales [ACTUALIZAR]
+
+- Score Total: 3.88/5.0
+- Umbral Mínimo: 3.5
+- Ahorro de Costos AI: 100%
+- Duración: 3ms
+- Estado: PASS
+
+### Distribución de Puntos
+
+| Perspectiva | Peso | Score | Estado |
+|-------------|------|-------|--------|
+| Local Structure | 40 pts | 40/40 | Pass |
+| Content Quality | 80 pts | 62/80 | Warning |
+| AI Assessment | 10 pts | N/A | Skipped |
+| Total | 130 pts | 102/130 | 78% |
+
+### Análisis por Categoría
+
+- IMPLEMENTED: 0 issues
+- USER_ACTION: 1 issue
+- KNOWN_LIMITATION: 0 issues
+- IMPROVEMENT: 4 issues
+
+---
+
+## Fortalezas (Mantener)
+
+1. Estructura Local Completa
+   - Archivos requeridos presentes
+   - JSON válidos
+   - Formato markdown consistente
+
+2. Features Opcionales Utilizadas
+   - API Contracts generados
+   - Framework Instructions presentes
+
+---
+
+## Áreas de Mejora (Priorizadas)
+
+### Alta Prioridad
+
+#### 1. Documentation Completeness
+Issue: Faltan secciones requeridas en summary.md  
+Categoría: IMPROVEMENT  
+Severidad: HIGH  
+Impacto: +8 pts
+
+Checklist:
+- [ ] Agregar sección Overview
+- [ ] Agregar sección Purpose
+- [ ] Agregar sección Features
+
+Template para fix:
+```
+## Overview
+[Breve descripción del proyecto]
+
+## Purpose  
+[Propósito principal]
+
+## Features
+- Feature 1: [descripción]
+- Feature 2: [descripción]
+```
+
+Owner: [ASIGNAR]  
+Deadline: [FECHA]
+
+---
+
+#### 2. Entry Point Documentation
+Issue: Entry points sin descripciones detalladas  
+Categoría: IMPROVEMENT  
+Severidad: MEDIUM  
+Impacto: +10 pts
+
+Checklist:
+- [ ] Usar headers para cada entry point
+- [ ] Agregar descripción de propósito
+- [ ] Documentar parámetros
+- [ ] Listar dependencias
+
+Template para fix:
+```
+### server.js
+Purpose: Punto de entrada principal
+Parameters: PORT, NODE_ENV
+Dependencies: express, cors
+```
+
+Owner: [ASIGNAR]  
+Deadline: [FECHA]
+
+---
+
+### Media Prioridad
+
+#### 3. Generic Phrases
+Issue: Descripciones contienen frases genéricas  
+Categoría: IMPROVEMENT  
+Severidad: MEDIUM  
+Impacto: +5 pts
+
+Ejemplos a corregir:
+- Antes: This project contains API endpoints
+- Después: REST API providing user authentication
+
+Owner: [ASIGNAR]  
+Deadline: [FECHA]
+
+---
+
+### Baja Prioridad
+
+#### 4. Freshness Tracking
+Issue: No hay tracking de freshness  
+Categoría: USER_ACTION  
+Severidad: LOW  
+Impacto: Mejor mantenibilidad
+
+Acción:
+```
+af init  # Re-generar contexto periódicamente
+```
+
+Frecuencia recomendada: Semanal o al inicio de cada sprint
+
+---
+
+## Plan de Acción
+
+### Inmediato (Esta semana)
+
+| # | Tarea | Impacto | Owner | Deadline | Status |
+|---|-------|---------|-------|----------|--------|
+| 1 | Completar summary.md | +8 pts | TBD | TBD | Pending |
+| 2 | Mejorar entrypoints.md | +10 pts | TBD | TBD | Pending |
+
+### Corto Plazo (Próximo sprint)
+
+| # | Tarea | Impacto | Owner | Deadline | Status |
+|---|-------|---------|-------|----------|--------|
+| 3 | Revisar frases genéricas | +5 pts | TBD | TBD | Pending |
+| 4 | Habilitar freshness tracking | N/A | TBD | TBD | Pending |
+
+---
+
+## Proyección de Mejora
+
+### Escenarios
+
+| Escenario | Score Actual | Score Proyectado | Cambio |
+|-----------|--------------|------------------|--------|
+| Conservador | 3.88 | 4.05 | +0.17 |
+| Completo | 3.88 | 4.20 | +0.32 |
+
+### ROI Esperado
+
+- Tiempo estimado: 2-3 horas
+- Mejora en score: +0.32 puntos
+- Impacto en calidad de AI: Mayor comprensión
+- Ahorro continuo: Mantiene 100% ahorro
+
+---
+
+## Checklist de Seguimiento
+
+### Implementación
+- [ ] Mejora #1 implementada
+- [ ] Mejora #2 implementada
+- [ ] Mejora #3 implementada (opcional)
+- [ ] Mejora #4 implementada (opcional)
+
+### Verificación
+- [ ] Re-ejecutar evaluator
+- [ ] Validar nuevo score >= 4.0
+- [ ] Confirmar que no hay regresiones
+- [ ] Actualizar este documento
+
+### Documentación
+- [ ] Actualizar CHANGELOG
+- [ ] Crear PR con cambios
+- [ ] Revisión de código
+- [ ] Merge a main
+
+---
+
+## Notas Adicionales
+
+### Lecciones Aprendidas
+[ESPACIO PARA NOTAS]
+
+### Bloqueos Identificados
+[DOCUMENTAR SI HAY BLOQUEOS]
+
+### Recursos Útiles
+- Guía de escritura: [LINK]
+- Template summary.md: [LINK]
+- Ejemplos entry points: [LINK]
+
+---
+
+Documento generado por: AI-First Evaluator v1.0.0  
+Última actualización: 2026-03-28

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-first-cli",
-  "version": "1.3.6",
+  "version": "1.3.8",
   "description": "CLI tool that prepares any repository to be used effectively by AI coding agents",
   "main": "dist/index.js",
   "type": "module",
@@ -16,7 +16,11 @@
     "docs:dev": "vitepress dev docs",
     "docs:build": "vitepress build docs",
     "docs:preview": "vitepress preview docs",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm run build",
+    "postinstall": "if [ -d node_modules/ai-first-evaluator ]; then cd node_modules/ai-first-evaluator && npm install && npm run build 2>/dev/null || true; fi",
+    "evaluate": "node node_modules/ai-first-evaluator/dist/core/evaluation/run-evaluation.js --config evaluator.config.json 2>/dev/null || echo 'Evaluator not installed'",
+    "evaluate:ci": "node node_modules/ai-first-evaluator/dist/core/evaluation/run-evaluation.js --config evaluator.config.json --compare-baseline --save-baseline 2>/dev/null || echo 'Evaluator not installed'",
+    "evaluate:quick": "node node_modules/ai-first-evaluator/dist/core/evaluation/run-evaluation.js --config evaluator.config.json --skip-ai 2>/dev/null || echo 'Evaluator not installed'"
   },
   "keywords": [
     "ai",
@@ -27,7 +31,9 @@
     "development",
     "tool",
     "code-analysis",
-    "indexing"
+    "indexing",
+    "mcp",
+    "model-context-protocol"
   ],
   "author": "Julian Perez Pesce <julian@example.com> (https://github.com/julianperezpesce)",
   "license": "MIT",
@@ -47,7 +53,11 @@
     "vitest": "^4.1.0",
     "vue": "^3.5.30"
   },
+  "optionalDependencies": {
+    "ai-first-evaluator": "git+https://github.com/julianperezpesce/ai-first-evaluator.git"
+  },
   "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.4",
     "chokidar": "^5.0.0",
     "ora": "^9.3.0",
     "sql.js": "^1.10.0"

package/src/analyzers/techStack.ts

@@ -208,7 +208,53 @@ function detectFrameworks(files: FileInfo[], fileNames: Set<string>, rootDir: st
       frameworks.push("Spring Boot");
     }
   } catch {}
-  
+   
+  // Detect Python frameworks from requirements.txt, Pipfile, pyproject.toml
+  try {
+    const pythonFrameworkMap: Record<string, string[]> = {
+      "django": ["Django"],
+      "flask": ["Flask"],
+      "fastapi": ["FastAPI"],
+      "tornado": ["Tornado"],
+      "pyramid": ["Pyramid"],
+      "bottle": ["Bottle"],
+      "cherrypy": ["CherryPy"],
+    };
+    
+    // Check requirements.txt
+    const reqPath = path.join(rootDir, "requirements.txt");
+    if (fs.existsSync(reqPath)) {
+      const reqContent = readFile(reqPath);
+      for (const [dep, names] of Object.entries(pythonFrameworkMap)) {
+        if (reqContent.toLowerCase().includes(dep.toLowerCase()) && !frameworks.some(f => names.includes(f))) {
+          frameworks.push(...names);
+        }
+      }
+    }
+    
+    // Check Pipfile
+    const pipfilePath = path.join(rootDir, "Pipfile");
+    if (fs.existsSync(pipfilePath)) {
+      const pipfileContent = readFile(pipfilePath);
+      for (const [dep, names] of Object.entries(pythonFrameworkMap)) {
+        if (pipfileContent.toLowerCase().includes(dep.toLowerCase()) && !frameworks.some(f => names.includes(f))) {
+          frameworks.push(...names);
+        }
+      }
+    }
+    
+    // Check pyproject.toml
+    const pyprojectPath = path.join(rootDir, "pyproject.toml");
+    if (fs.existsSync(pyprojectPath)) {
+      const pyprojectContent = readFile(pyprojectPath);
+      for (const [dep, names] of Object.entries(pythonFrameworkMap)) {
+        if (pyprojectContent.toLowerCase().includes(dep.toLowerCase()) && !frameworks.some(f => names.includes(f))) {
+          frameworks.push(...names);
+        }
+      }
+    }
+  } catch {}
+   
   // Detect SwiftUI from Swift files
   const swiftFiles = files.filter(f => f.extension === "swift");
   for (const swiftFile of swiftFiles) {

package/src/commands/ai-first.ts

@@ -31,6 +31,7 @@ import { runIncrementalUpdate, detectChangedFiles } from "../core/incrementalAna
 import { generateAllSchema } from "../core/schema.js";
 import { Database } from "sql.js";
 import ora from "ora";
+import { startMCP } from "../mcp/index.js";
 import process from "process";
 
 const __filename = fileURLToPath(import.meta.url);
@@ -1077,6 +1078,8 @@ Options:
   } else if (command === 'init' || !command) {
     // Init command - generate all context files
     if (command === 'init') args.shift();
+    
+    let preset: string | undefined;
 
     for (let i = 0; i < args.length; i++) {
       const arg = args[i];
@@ -1089,6 +1092,10 @@ Options:
         case "-o":
           options.outputDir = args[++i];
           break;
+        case "--preset":
+        case "-p":
+          preset = args[++i];
+          break;
         case "--help":
         case "-h":
           console.log(`
@@ -1106,18 +1113,45 @@ Commands:
   doctor               Check repository health and AI readiness
   explore <module>     Explore module dependencies
   map                  Generate repository map (files, modules, graph)
-  adapters              List available adapters
-  explore <module>     Explore module dependencies
-  map                  Generate repository map (files, modules, graph)
+  adapters             List available adapters
+  git                  Show git activity and recent changes
+  graph                Build knowledge graph
+  update               Update context incrementally
+  mcp                  Start MCP server for AI agents
 
 Options:
   -r, --root <dir>      Root directory to scan (default: current directory)
   -o, --output <dir>   Output directory (default: ./ai-context)
+  -p, --preset <name>  Use preset (full, quick, api, docs)
   -h, --help           Show help message
+
+Presets:
+  full    Complete analysis with all features
+  quick   Fast analysis for development iterations
+  api     Focus on API endpoints and services
+  docs    Documentation files only
 `);
           process.exit(0);
       }
     }
+    
+    const rootDir = options.rootDir || process.cwd();
+    const configPath = path.join(rootDir, 'ai-first.config.json');
+    if (fs.existsSync(configPath)) {
+      try {
+        const config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+        if (config.output?.directory && !options.outputDir) {
+          options.outputDir = path.join(rootDir, config.output.directory);
+        }
+        if (config.preset && !preset) {
+          preset = config.preset;
+        }
+      } catch {}
+    }
+    
+    if (preset) {
+      console.log(`\n🎛️  Using preset: ${preset}\n`);
+    }
 
     runAIFirst(options).then((result) => {
       process.exit(result.success ? 0 : 1);
@@ -1491,7 +1525,52 @@ Examples:
     }
     
     process.exit(0);
-    process.exit(0);
+  } else if (command === 'mcp') {
+    // MCP command - start Model Context Protocol server
+    args.shift();
+    
+    if (args.includes('--help') || args.includes('-h')) {
+      console.log(`
+ai-first mcp - Start Model Context Protocol server
+
+Usage: ai-first mcp [options]
+
+Options:
+  -r, --root <dir>    Root directory to scan (default: current directory)
+  -h, --help          Show help message
+
+Description:
+  Starts an MCP server that allows AI agents (Claude Desktop, etc.) to
+  query repository context using the Model Context Protocol.
+
+The server provides these tools:
+  - generate_context: Generate AI context for the repository
+  - index_repo: Create SQLite index for fast queries
+  - query_symbol: Look up symbols by name
+  - get_architecture: Get architecture analysis
+  - get_tech_stack: Get technology stack information
+
+Examples:
+  ai-first mcp                    # Start MCP server in current directory
+  ai-first mcp --root ./my-project # Start with specific root directory
+`);
+      process.exit(0);
+    }
+    
+    let rootDir = process.cwd();
+    
+    for (let i = 0; i < args.length; i++) {
+      const arg = args[i];
+      if (arg === "--root" || arg === "-r") rootDir = args[++i];
+    }
+    
+    console.log("\n🚀 Starting MCP server...\n");
+    console.log(`   Root directory: ${rootDir}`);
+    console.log("   Protocol: stdio");
+    console.log("\n   The server is now running and ready to accept MCP requests.");
+    console.log("   Use Ctrl+C to stop.\n");
+    
+    startMCP({ rootDir });
   } else {
     console.log(`Unknown command: ${command}`);
     console.log(`Use 'ai-first --help' for usage information`);