ai-first-cli 1.1.1 → 1.1.2

package/docs/es/guide/adapters.md

@@ -0,0 +1,143 @@
+# Adaptadores de Análisis
+
+AI-First usa un sistema de adaptadores para soportar múltiples lenguajes y frameworks sin modificar el motor de análisis central.
+
+## Descripción General
+
+Los adaptadores personalizan cómo AI-First detecta:
+- **Raíces de características**: Dónde buscar características de negocio
+- **Puntos de entrada**: Archivos que representan puntos de entrada
+- **Capas**: Capas arquitectónicas en el código base
+- **Carpetas ignoradas**: Directorios técnicos a omitir
+
+## Adaptadores Soportados
+
+| Adaptador | Señales de Detección |
+|-----------|---------------------|
+| JavaScript/TypeScript | `package.json`, `tsconfig.json`, `vite.config.ts` |
+| Django | `manage.py`, `settings.py` |
+| Flask/FastAPI | `app.py`, `main.py` |
+| Ruby on Rails | `Gemfile`, `config.ru` |
+| Salesforce | `sfdx-project.json`, `force-app/` |
+| .NET | `*.csproj`, `Program.cs` |
+| ASP.NET Core | `Startup.cs`, `Program.cs` |
+| Blazor | `_Imports.razor`, `@page` |
+
+## Arquitectura
+
+```
+analysis/
+adapters/
+  baseAdapter.ts      # Definición de interfaz
+  javascriptAdapter.ts
+  pythonAdapter.ts
+  railsAdapter.ts
+  salesforceAdapter.ts
+  dotnetAdapter.ts
+  adapterRegistry.ts  # Lógica de detección
+```
+
+## Interfaz del Adaptador
+
+```typescript
+interface AnalysisAdapter {
+  name: string;
+  displayName: string;
+  detectionSignals: DetectionSignal[];
+  featureRoots: string[];
+  ignoredFolders: string[];
+  entrypointPatterns: string[];
+  layerRules: LayerRule[];
+  supportedExtensions: string[];
+  flowEntrypointPatterns: string[];
+  flowExcludePatterns: string[];
+}
+```
+
+## Señales de Detección
+
+Los adaptadores se detectan usando señales:
+
+```typescript
+interface DetectionSignal {
+  type: 'file' | 'directory' | 'content';
+  pattern: string;
+  contentPattern?: string;
+}
+```
+
+Ejemplo:
+```typescript
+detectionSignals: [
+  { type: 'file', pattern: 'package.json' },
+  { type: 'file', pattern: 'tsconfig.json' },
+  { type: 'directory', pattern: 'src' }
+]
+```
+
+## Reglas de Capas
+
+Cada adaptador define capas arquitectónicas:
+
+```typescript
+layerRules: [
+  { name: 'api', priority: 1, patterns: ['controller', 'handler', 'route'] },
+  { name: 'service', priority: 2, patterns: ['service', 'usecase'] },
+  { name: 'data', priority: 3, patterns: ['repository', 'model'] }
+]
+```
+
+## Uso
+
+```typescript
+import { detectAdapter, getAdapter } from './core/adapters/index.js';
+
+// Auto-detectar tipo de proyecto
+const adapter = detectAdapter('/path/to/project');
+console.log(adapter.name); // 'javascript', 'django', etc.
+
+// Obtener adaptador específico
+const jsAdapter = getAdapter('javascript');
+```
+
+## Creando Adaptadores Personalizados
+
+1. Crea un nuevo archivo en `src/core/adapters/`
+2. Define tu adaptador:
+
+```typescript
+import { AnalysisAdapter } from './baseAdapter.js';
+
+export const myAdapter: AnalysisAdapter = {
+  name: 'myframework',
+  displayName: 'My Framework',
+  detectionSignals: [
+    { type: 'file', pattern: 'my-framework.config.js' }
+  ],
+  featureRoots: ['src', 'lib'],
+  ignoredFolders: ['node_modules', 'dist'],
+  entrypointPatterns: ['controller', 'service'],
+  layerRules: [
+    { name: 'api', priority: 1, patterns: ['controller'] },
+    { name: 'service', priority: 2, patterns: ['service'] },
+    { name: 'data', priority: 3, patterns: ['model'] }
+  ],
+  supportedExtensions: ['.ts', '.js'],
+  flowEntrypointPatterns: ['controller'],
+  flowExcludePatterns: ['test', 'spec']
+};
+```
+
+3. Regístralo en `adapterRegistry.ts`
+4. Agrega tests
+
+## Integración
+
+Los adaptadores se integran con la detección de características y flujos:
+
+- `featureRoots` → dónde encontrar características
+- `ignoredFolders` → qué omitir
+- `entrypointPatterns` → puntos de entrada de lógica de negocio
+- `layerRules` → capas de la cadena de flujos
+
+Esto permite que AI-First entienda cualquier estructura de código base.

package/docs/es/guide/ai-repository-schema.md

@@ -0,0 +1,119 @@
+# Esquema de Repositorio AI
+
+El Esquema de Repositorio AI estandariza cómo AI-First almacena y administra los metadatos del repositorio, permitiendo que los agentes de IA comprendan la estructura del proyecto y mantengan compatibilidad entre versiones.
+
+## Descripción General
+
+AI-First genera tres archivos de esquema principales que definen la estructura del proyecto:
+
+- `schema.json` - Versión del esquema y metadatos
+- `project.json` - Información del proyecto (features, flows, lenguajes, frameworks)
+- `tools.json` - Herramientas y agentes de IA compatibles
+
+## Archivos de Esquema
+
+### schema.json
+
+Contiene la versión del esquema y metadatos de generación:
+
+```json
+{
+  "schemaVersion": "1.0",
+  "generatedBy": "ai-first",
+  "generatedAt": "2024-01-15T10:30:00.000Z"
+}
+```
+
+### project.json
+
+Contiene información específica del proyecto:
+
+```json
+{
+  "name": "mi-proyecto",
+  "rootDir": "/ruta/al/proyecto",
+  "features": ["auth", "users", "payments"],
+  "flows": ["login", "checkout", "registration"],
+  "languages": ["TypeScript", "Python"],
+  "frameworks": ["Express", "React"],
+  "generatedAt": "2024-01-15T10:30:00.000Z"
+}
+```
+
+### tools.json
+
+Define los agentes de IA compatibles:
+
+```json
+{
+  "compatibleAgents": ["ai-first-bridge", "opencode", "cursor", "windsurf", "cline"],
+  "schemaVersion": "1.0"
+}
+```
+
+## Detección Automática
+
+AI-First detecta automáticamente:
+
+- **Features**: Desde archivos `ai/context/features/*.json`
+- **Flows**: Desde archivos `ai/context/flows/*.json`
+- **Lenguajes**: Desde `ai/tech_stack.md` (sección Languages)
+- **Frameworks**: Desde `ai/tech_stack.md` (sección Frameworks)
+
+## Compatibilidad de Versiones
+
+El esquema usa versionamiento semántico. AI-First valida la compatibilidad:
+
+- Misma versión mayor = compatible
+- Diferente versión mayor = incompatible
+
+## Comandos CLI
+
+### Generar Esquema
+
+El esquema se genera automáticamente con `ai-first init`:
+
+```bash
+ai-first init
+```
+
+### Validar Esquema
+
+Verifica si tu repositorio tiene un esquema válido:
+
+```javascript
+import { validateSchema } from 'ai-first';
+
+const result = validateSchema('./ai');
+console.log(result.valid);  // true/false
+console.log(result.errors); // []
+```
+
+### Cargar Esquema
+
+Carga el esquema programáticamente:
+
+```javascript
+import { loadFullSchema } from 'ai-first';
+
+const schema = loadFullSchema('./ai');
+if (schema) {
+  console.log(schema.project.name);
+  console.log(schema.schema.schemaVersion);
+}
+```
+
+## Integración
+
+El esquema está integrado en el CLI de AI-First:
+
+1. `ai-first init` - Genera archivos de esquema
+2. `ai-first validate` - Valida el esquema (próximamente)
+3. `ai-first doctor` - Verifica la salud del esquema
+
+## Beneficios
+
+- **Seguridad de Versión**: Los agentes de IA saben qué versión del esquema esperar
+- **Descubrimiento de Proyecto**: Features y flows se detectan automáticamente
+- **Compatibilidad de Agentes**: Lista clara de herramientas de IA compatibles
+- **Extensibilidad**: El esquema puede extenderse para agentes personalizados

package/docs/es/guide/features.md

@@ -0,0 +1,67 @@
+# Detección de Características
+
+AI-First detecta automáticamente características empresariales y flujos desde la estructura de tu código base.
+
+## Reglas de Detección de Características
+
+### 1. Raíces de Candidatos
+
+Las características se escanean dentro de:
+- `src/*`
+- `app/*`
+- `packages/*`
+- `services/*`
+- `modules/*`
+- `features/*`
+
+### 2. Carpetas Ignoradas
+
+Las carpetas técnicas son excluidas:
+- `utils`, `helpers`, `types`, `interfaces`, `constants`
+- `config`, `dto`, `models`, `common`, `shared`
+
+### 3. Requisitos de Características
+
+Una característica válida debe:
+- Contener al menos 3 archivos fuente
+- Contener al menos un punto de entrada (Controller, Route, Handler, Command, Service)
+- Existir en profundidad 1 o 2: `src/auth`, `src/modules/auth`
+
+## Formato de Salida de Características
+
+```json
+{
+  "name": "auth",
+  "path": "src/auth",
+  "files": [
+    "src/auth/authController.ts",
+    "src/auth/authService.ts",
+    "src/auth/authRepository.ts"
+  ],
+  "entrypoints": [
+    "src/auth/authController.ts"
+  ],
+  "dependencies": ["users", "payments"]
+}
+```
+
+## Detección de Flujos
+
+Los flujos representan cadenas de ejecución empresarial que comienzan desde puntos de entrada:
+
+- **Mínimo 3 archivos** por flujo
+- **Mínimo 2 capas arquitectónicas** (api → service → data)
+- Puntos de entrada: Controller, Route, Handler, Command
+
+Los flujos se generan usando tres métodos de respaldo:
+1. **Grafo de Símbolos** - Usa relaciones de llamada/importación
+2. **Estructura de Carpetas** - Agrupa por prefijo de característica
+3. **Análisis de Importaciones** - Sigue cadenas de dependencias
+
+## Ubicación de Salida
+
+Las características y flujos se escriben en:
+```
+ai/context/features/<caracteristica>.json
+ai/context/flows/<flujo>.json
+```

package/docs/es/guide/flows.md

@@ -0,0 +1,134 @@
+# Detección de Flujos
+
+Los flujos representan cadenas de ejecución empresarial que atraviesan múltiples capas arquitectónicas en tu código base.
+
+## Descripción General
+
+La detección de flujos identifica cómo fluyen los datos a través de tu aplicación desde los puntos de entrada hasta las capas de acceso a datos.
+
+### Ejemplo de Flujo
+
+```
+LoginController → AuthService → UserRepository
+```
+
+Esto representa una arquitectura de tres niveles típica:
+1. **Capa API**: LoginController (punto de entrada)
+2. **Capa de Servicio**: AuthService (lógica de negocio)
+3. **Capa de Datos**: UserRepository (persistencia)
+
+## Métodos de Detección
+
+AI-First usa múltiples métodos de respaldo para detectar flujos:
+
+### 1. Grafo de Símbolos (Primario)
+
+Cuando las relaciones de símbolos son fuertes, los flujos se detectan analizando:
+- Llamadas de funciones (`calls`)
+- Importaciones de módulos (`imports`)
+- Referencias de símbolos (`references`)
+
+**Requisitos:**
+- Densidad del grafo de símbolos ≥ 0.5
+- Al menos 10 relaciones
+
+### 2. Estructura de Carpetas (Respaldo)
+
+ Cuando el grafo de símbolos es débil, los flujos se infieren de:
+- Convenciones de nombres de archivos (ej. `authController.ts`, `authService.ts`)
+- Agrupación por prefijo de característica
+
+**Ejemplo:**
+- `authController.ts` → característica: `auth`
+- `authService.ts` → pertenece al flujo `auth`
+- `authRepository.ts` → pertenece al flujo `auth`
+
+### 3. Análisis de Importaciones (Respaldo)
+
+Usa el análisis de dependencias para rastrear rutas de ejecución:
+1. Iniciar desde archivos de punto de entrada
+2. Seguir declaraciones de importación
+3. Construir cadena hasta MAX_FLOW_DEPTH
+
+## Configuración
+
+### Límites
+
+| Parámetro | Valor | Descripción |
+|-----------|-------|-------------|
+| `MAX_FLOW_DEPTH` | 5 | Profundidad máxima de recorrido |
+| `MAX_FLOW_FILES` | 30 | Máximo de archivos por flujo |
+
+### Puntos de Entrada
+
+Los flujos deben comenzar desde uno de estos tipos de archivos:
+- Controller
+- Route
+- Handler
+- Command
+
+### Capas
+
+Capas arquitectónicas soportadas:
+| Capa | Patrones |
+|-------|----------|
+| api | controller, handler, route, router, endpoint |
+| service | service, services, usecase, interactor |
+| data | repository, repo, dal, dao, data, persistence |
+| domain | model, entity, schema, domain |
+
+## Requisitos
+
+Un flujo válido debe tener:
+- **Mínimo 3 archivos**
+- **Mínimo 2 capas arquitectónicas**
+
+## Formato de Salida
+
+Los flujos se escriben en: `ai/context/flows/<nombre-flujo>.json`
+
+```json
+{
+  "name": "auth",
+  "entrypoint": "api/authController.js",
+  "files": [
+    "api/authController.js",
+    "services/authService.js",
+    "data/authRepository.js"
+  ],
+  "depth": 3,
+  "layers": ["api", "service", "data"]
+}
+```
+
+### Campos de Salida
+
+| Campo | Descripción |
+|-------|-------------|
+| `name` | Identificador del flujo (derivado del punto de entrada) |
+| `entrypoint` | Archivo de inicio (Controller/Route/Handler/Command) |
+| `files` | Todos los archivos en la cadena del flujo |
+| `depth` | Profundidad real del recorrido |
+| `layers` | Capas únicas recorridas |
+
+## Uso
+
+Los flujos se generan automáticamente al ejecutar:
+
+```bash
+ai-first map
+# o
+ai-first init
+```
+
+## Integración
+
+Los flujos funcionan con las Características para proporcionar contexto completo:
+
+- **Características**: Identifican módulos de negocio (auth, users, payments)
+- **Flujos**: Identifican cómo se ejecuta el código dentro de las características
+
+Juntos permiten a los agentes de IA:
+1. Entender la estructura del dominio de negocio
+2. Rastrear rutas de ejecución
+3. Localizar código relevante para modificaciones

package/docs/es/guide/git-intelligence.md

@@ -0,0 +1,170 @@
+# Inteligencia Git
+
+AI-First puede analizar tu repositorio git para proporcionar a los agentes IA contexto sobre la actividad reciente, ayudándolos a priorizar archivos relevantes y entender qué ha sido modificado recientemente.
+
+## Por qué Inteligencia Git?
+
+Cuando trabajas con asistentes de codificación IA, conocer qué archivos han sido modificados recientemente ayuda a la IA a:
+
+- **Priorizar revisión** - Enfocarse en archivos modificados recently al sugerir modificaciones
+- **Entender contexto** - Saber qué features/flows están siendo desarrollados activamente
+- **Evitar conflictos** - Identificar archivos que fueron modificados recientemente para prevenir sobreescritura
+- **Rastrear cambios** - Ver patrones de commits y frecuencia de actividad
+
+## Cómo Funciona
+
+La Inteligencia Git analiza tu historial git para generar metadata sobre la actividad reciente del repositorio:
+
+1. **Detecta repositorio git** - Verifica si el proyecto es un repositorio git
+2. **Analiza commits recientes** - Extrae datos de commits (default: últimos 50 commits, últimos 30 días)
+3. **Mapea a features/flows** - Correlaciona archivos cambiados con features y flows detectados
+4. **Genera metadata** - Archivos JSON de salida para consumo de IA
+
+## Archivos Generados
+
+Cuando ejecutas `ai-first git`, los siguientes archivos se crean en `ai/git/`:
+
+### recent-files.json
+
+Lista de archivos recientemente cambiados:
+
+```json
+[
+  "src/auth/loginController.ts",
+  "src/auth/sessionService.ts",
+  "src/payments/checkoutFlow.ts"
+]
+```
+
+### recent-features.json
+
+Features que han sido modificados recientemente:
+
+```json
+["auth", "payments"]
+```
+
+### recent-flows.json
+
+Flows que han sido modificados recientemente:
+
+```json
+["login", "checkout"]
+```
+
+### commit-activity.json
+
+Datos detallados de frecuencia de commits:
+
+```json
+{
+  "totalCommits": 50,
+  "dateRange": {
+    "start": "2026-02-01",
+    "end": "2026-03-10"
+  },
+  "files": {
+    "src/auth/loginController.ts": 5,
+    "src/auth/sessionService.ts": 3
+  },
+  "features": {
+    "auth": 8,
+    "payments": 12
+  },
+  "flows": {
+    "login": 4,
+    "checkout": 7
+  }
+}
+```
+
+## Uso
+
+### Comando CLI
+
+```bash
+# Analizar actividad git
+ai-first git
+
+# Analizar con más commits
+ai-first git --limit 100
+
+# Mostrar actividad detallada
+ai-first git --activity
+
+# Salida como JSON
+ai-first git --json
+```
+
+### Opciones
+
+| Opción | Alias | Descripción |
+|--------|-------|-------------|
+| `--root` | `-r` | Directorio raíz (default: actual) |
+| `--limit` | `-n` | Número de commits (default: 50) |
+| `--activity` | `-a` | Mostrar actividad detallada |
+| `--json` | | Salida como JSON |
+| `--help` | `-h` | Mostrar ayuda |
+
+### Uso Programático
+
+```typescript
+import { 
+  detectGitRepository,
+  getRecentCommits,
+  analyzeGitActivity,
+  generateGitContext 
+} from 'ai-first';
+
+// Verificar si es repo git
+if (detectGitRepository('/path/to/project')) {
+  // Obtener commits recientes
+  const commits = getRecentCommits('/path/to/project');
+  
+  // Analizar actividad
+  const activity = analyzeGitActivity('/path/to/project');
+  
+  // Generar archivos de contexto
+  const context = generateGitContext('/path/to/project');
+}
+```
+
+## Referencia API
+
+### detectGitRepository(rootDir: string): boolean
+
+Verifica si un directorio es un repositorio git.
+
+### getRecentCommits(rootDir: string, limit?: number): GitCommit[]
+
+Retorna commits recientes con cambios de archivos.
+
+### extractChangedFiles(commits: GitCommit[]): RecentFile[]
+
+Extrae y cuenta archivos cambiados de commits.
+
+### mapFilesToFeatures(rootDir: string, files: string[]): string[]
+
+Mapea archivos cambiados a features detectados.
+
+### mapFilesToFlows(rootDir: string, files: string[]): string[]
+
+Mapea archivos cambiados a flows detectados.
+
+### analyzeGitActivity(rootDir: string): GitActivity | null
+
+Analiza actividad git y retorna datos agregados.
+
+### generateGitContext(rootDir: string, aiDir?: string): GitContext
+
+Genera todos los archivos de contexto git en `ai/git/`.
+
+## Integración con Contexto IA
+
+La inteligencia git se integra con el sistema de contexto IA:
+
+1. Ejecuta `ai-first init` para generar features y flows
+2. Ejecuta `ai-first git` para analizar actividad git
+3. Los agentes IA pueden leer los archivos en `ai/git/` para entender cambios recientes
+
+Esto proporciona una imagen completa de la estructura de tu código y su actividad de desarrollo.