ai-first-cli 1.1.0 → 1.1.2

package/CHANGELOG.md

@@ -6,6 +6,62 @@ All notable changes to `ai-first` will be documented in this file.
 
 ## [Unreleased]
 
+### Added
+- **CLI Progress Feedback**: Added ora-based progress indicators for repository analysis
+- **Lazy Context Generation**: Staged indexing for faster CLI startup (Stage 1 minimal, Stage 2 on-demand)
+- **Lazy Analyzer Module**: `src/core/lazyAnalyzer.ts` with buildMinimalIndex, expandFeatureContext, expandFlowContext
+- **Lazy Indexing Tests**: Comprehensive test suite for lazy context generation
+- **Lazy Indexing Documentation**: English and Spanish guides for lazy context generation
+- **AI Repository Schema**: Standardized schema system for AI-First metadata (schema.json, project.json, tools.json)
+- **AI Repository Schema**: Standardized schema system for AI-First metadata (schema.json, project.json, tools.json)
+- **Schema CLI Integration**: Schema automatically generated with `ai-first init`
+- **Schema Validation**: Programmatic schema validation API
+- **Schema Tests**: Comprehensive test suite for schema generation and validation
+- **Schema Documentation**: English and Spanish guides for AI Repository Schema
+- **Incremental Analysis**: Update repository context incrementally when files change
+- **Incremental Analysis**: Update repository context incrementally when files change
+- **Update CLI Command**: `ai-first update` to perform incremental updates
+- **Self-Healing Context**: AI context updates automatically when files change
+- **Repository Knowledge Graph**: Unify all repository intelligence into a single navigable graph
+- **Graph CLI Command**: `ai-first graph` to generate knowledge graph
+- **Repository Knowledge Graph**: Unify all repository intelligence into a single navigable graph
+- **Graph CLI Command**: `ai-first graph` to generate knowledge graph
+- **Graph Output**: `ai/graph/knowledge-graph.json` with nodes and edges
+- **Git Intelligence**: Analyze git activity to provide AI context about recently changed files, features, and flows
+- **Git CLI Command**: `ai-first git` to analyze repository activity and generate metadata
+- **Git Intelligence**: Analyze git activity to provide AI context about recently changed files, features, and flows
+- **Git CLI Command**: `ai-first git` to analyze repository activity and generate metadata
+- **Git Context Files**: `ai/git/recent-files.json`, `ai/git/recent-features.json`, `ai/git/recent-flows.json`, `ai/git/commit-activity.json`
+- **Adapter SDK**: Developer-friendly `createAdapter()` API for creating custom ecosystem adapters
+- **Community Adapters**: Pre-built adapters for Laravel, NestJS, Spring Boot, Phoenix, FastAPI
+- **Adapter CLI Command**: `ai-first adapters` to list all available adapters
+- **Adapter SDK**: Developer-friendly `createAdapter()` API for creating custom ecosystem adapters
+- **Community Adapters**: Pre-built adapters for Laravel, NestJS, Spring Boot, Phoenix, FastAPI
+- **Adapter CLI Command**: `ai-first adapters` to list all available adapters
+- Enhanced symbol indexing with `filePath#symbolName` IDs
+- Enhanced symbol indexing with `filePath#symbolName` IDs
+- Extended symbol graph relationships: calls, called_by, imports, references, instantiates, extends, implements, exports
+- Reverse symbol references (`ai/graph/symbol-references.json`)
+- File index with symbol mappings (`ai/files.json`)
+- Code Context Packets (CCP) with depth, ranking, and multiple formats
+- Context CLI flags: `--depth`, `--max-symbols`, `--format`, `--save`
+- Incremental indexing with file hash cache (`ai/index-state.json`)
+- Context ranking system based on graph distance and relationships
+- Android/Kotlin Support: Android framework detection, SDK version extraction, Gradle dependency parsing, AndroidManifest parsing, Android resources indexing, Gradle multi-module detection
+- **Business Feature Detection**: Auto-detect business modules (auth, users, payments) from codebase structure
+- **Flow Detection**: Generate execution chains spanning multiple architectural layers (api → service → data)
+- Feature output: `ai/context/features/<feature>.json` with path, files, entrypoints, dependencies
+- Flow output: `ai/context/flows/<flow>.json` with depth, layers, entrypoint
+- Support for nested features at depth 1 and 2 (src/auth, src/modules/auth)
+- **Performance Documentation**: Complete guide to incremental analysis and optimization
+- **Spanish Documentation**: Complete translation for all guides
+- **Adapter System**: Multi-language/framework support (JavaScript, Python, Django, Flask, Rails, Salesforce, .NET)
+- **Spanish Documentation**: Complete translation for all guides
+
+### Improved
+- Incremental repository analysis with change detection
+- Performance benchmarks for various repository sizes
+
 ### Added
 - Enhanced symbol indexing with `filePath#symbolName` IDs
 - Extended symbol graph relationships: calls, called_by, imports, references, instantiates, extends, implements, exports
@@ -15,6 +71,28 @@ All notable changes to `ai-first` will be documented in this file.
 - Context CLI flags: `--depth`, `--max-symbols`, `--format`, `--save`
 - Incremental indexing with file hash cache (`ai/cache.json`)
 - Context ranking system based on graph distance and relationships
+- Android/Kotlin Support: Android framework detection, SDK version extraction, Gradle dependency parsing, AndroidManifest parsing, Android resources indexing, Gradle multi-module detection
+- **Business Feature Detection**: Auto-detect business modules (auth, users, payments) from codebase structure
+- **Flow Detection**: Generate execution chains spanning multiple architectural layers (api → service → data)
+- Feature output: `ai/context/features/<feature>.json` with path, files, entrypoints, dependencies
+- Flow output: `ai/context/flows/<flow>.json` with depth, layers, entrypoint
+- Support for nested features at depth 1 and 2 (src/auth, src/modules/auth)
+
+---
+
+## [1.1.0] - 2026-03-09
+
+### Added
+- Enhanced symbol indexing with `filePath#symbolName` IDs
+- Extended symbol graph relationships: calls, called_by, imports, references, instantiates, extends, implements, exports
+- Reverse symbol references (`ai/graph/symbol-references.json`)
+- File index with symbol mappings (`ai/files.json`)
+- Code Context Packets (CCP) with depth, ranking, and multiple formats
+- Context CLI flags: `--depth`, `--max-symbols`, `--format`, `--save`
+- Incremental indexing with file hash cache (`ai/cache.json`)
+YB|- Context ranking system based on graph distance and relationships
+RR|- Android/Kotlin Support: Android framework detection, SDK version extraction, Gradle dependency parsing, AndroidManifest parsing, Android resources indexing, Gradle multi-module detection
+PY|- Documentation: Architecture guide and Commands reference updated
 - Documentation: Architecture guide and Commands reference updated
 
 ---

package/README.es.md

@@ -247,6 +247,17 @@ ai/
 ├── 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`
+    ├── features/      # Features de negocio detectados
+    │   └── <modulo>.json
+    └── flows/         # Cadenas de ejecución de negocio
+        └── <flujo>.json
 └── index.db           # SQLite (con índice ai-first)
 ```
 
@@ -278,8 +289,113 @@ ai-first init --output ./docs/ai
 
 # Directorio raíz personalizado
 ai-first init --root ./my-project
+TH|```
+TH|
+TH|## 📦 Context Control Packs (CCP)
+TH|
+TH|CCP (Context Control Packs) te permite crear contextos reutilizables y específicos para diferentes flujos de trabajo de IA.
+TH|
+TH|### Cómo Funciona
+TH|
+TH|1. **Generar Módulos de Contexto**: `ai-first init` crea módulos en `ai/context/`
+TH|2. **Crear un CCP**: Define qué módulos incluir para una tarea específica
+TH|3. **Usar en IA**: Referencia el CCP al trabajar con agentes de IA
+TH|
+TH|### Comandos CCP
+TH|
+TH|```bash
+TH|# Crear un nuevo CCP con módulos de contexto específicos
+TH|ai-first ccp create tarea-auth --include repo,auth,api --description "Trabajo en autenticación"
+TH|
+TH|# Listar todos los CCPs disponibles
+TH|ai-first ccp list
+TH|
+TH|# Mostrar detalles del CCP
+TH|ai-first ccp show tarea-auth
+TH|```
+TH|
+TH|### Estructura CCP
+TH|
+TH|```
+TH|ai/
+TH|├── context/           # Módulos de contexto (auto-generados)
+TH|│   ├── repo.json      # Contexto base del repositorio
+TH|│   ├── auth.json      # Contexto de autenticación
+TH|│   └── <feature>.json
+TH|│
+TH|└── ccp/              # Definiciones de CCP
+TH|    └── <nombre>/
+TH|        └── context.json
+TH|```
+TH|
+TH|Ejemplo CCP (context.json)
+TH|
+TH|```json
+TH|{
+TH|  "task": "auth-feature",
+TH|  "description": "Trabajo en autenticación",
+TH|  "includes": [
+TH|    "../../context/repo.json",
+TH|    "../../context/auth.json",
+TH|    "../../context/api.json"
+TH|  ]
+TH|}
+TH|```
+TH|
+Caso de uso: Crea contextos específicos como `"fix-bug"`, `"add-feature"`, `"refactor"`, etc.
+
+---
+
+## 🎯 Contextos Semánticos (Features & Flows)
+
+Los contextos semánticos son comprensión automática a nivel de negocio de tu código.
+
+### Features
+
+Los features representan módulos de negocio detectados desde la estructura del proyecto.
+
+**Filtros de calidad:**
+- Debe tener ≥ 3 archivos fuente
+- Debe contener un entrypoint (Controller, Route, Handler, Command, Service)
+- Excluidos: utils, helpers, types, interfaces, constants, config, models, dto, common
+
+```json
+// ai/context/features/<modulo>.json
+{
+  "feature": "auth",
+  "files": ["src/auth/controller.js", "src/auth/service.js"],
+  "entrypoints": ["src/auth/controller.js"]
+}
 ```
 
+### Flows
+
+Los flows representan cadenas de ejecución de negocio desde entrypoints.
+
+**Filtros de calidad:**
+- Debe abarcar ≥ 3 archivos
+- Debe cruzar ≥ 2 capas arquitectónicas (api → service → data)
+- Debe iniciar desde un entrypoint (Controller, Route, Command, Handler)
+
+```json
+// ai/context/flows/<nombre>.json
+{
+  "name": "login",
+  "entrypoint": "src/auth/controller.js",
+  "files": ["controller.js", "service.js", "repository.js"],
+  "depth": 3,
+  "layers": ["api", "service", "data"]
+}
+```
+
+**Generado por:** `ai-first init` o `ai-first map`
+
+---
+
+## 🌎 Idiomas
+TH|
+TH|---
+
 ---
 
 ## 🌎 Idiomas
@@ -344,7 +460,27 @@ Ver [docs/architecture.md](./docs/architecture.md) para arquitectura interna.
 ¡Danos una ⭐ si este proyecto te ayudó!
 
 ---
-
+KP|
+VT|## 🤖 Soporte Android/Kotlin
+HB|
+XZ|ai-first detecta e indexa automáticamente proyectos Android/Kotlin:
+HB|
+RV|- **Detección de lenguaje**: Kotlin (.kt)
+- **Detección de framework**: Android (vía build.gradle, AndroidManifest.xml)
+- **Análisis de dependencias**: Dependencias Gradle (implementation, api, compile)
+- **Puntos de entrada**: Activities, Services, BroadcastReceivers desde AndroidManifest.xml
+- **Recursos**: Indexa res/layout, res/drawable, res/values
+- **Multi-módulo**: Detecta módulos Gradle desde settings.gradle
+HB|
+XZ|### Archivos generados para proyectos Android
+HB|
+XZ|- `ai/tech_stack.md` - Muestra Android con versiones de SDK
+- `ai/dependencies.json` - Dependencias Gradle en formato group:artifact:version
+- `ai/entrypoints.md` - Activities, services, permisos de Android
+- `ai/android-resources.json` - Layouts, drawables, values (si existe res/)
+- `ai/gradle-modules.json` - Estructura multi-módulo (si existe settings.gradle)
+HB|
+VT|---
 ## 📄 Licencia
 
 MIT © [Julian Perez Pesce](https://github.com/julianperezpesce)

package/README.md

@@ -254,6 +254,17 @@ ai/
 │   ├── module-graph.json   # Module-level dependency graph
 │   └── symbol-graph.json   # Symbol-level relationships (calls, imports, etc.)
 │
+└── context/           # Generated by `ai-first init` or `map`
+    ├── features/      # Auto-detected business features
+    │   └── <module>.json
+    └── flows/         # Business execution chains
+        └── <flow>.json
+├── index.db          # SQLite (with ai-first index)
+│
+├── graph/             # Generated by `ai-first map`
+│   ├── module-graph.json   # Module-level dependency graph
+│   └── symbol-graph.json   # Symbol-level relationships (calls, imports, etc.)
+│
 └── context/           # Generated by `ai-first context <symbol>`
     └── <symbol>.json # Code Context Packets (CCP)
 ```
@@ -340,7 +351,63 @@ ai-first explore src
 ```
 
 The explore command generates a module dependency graph based on imports.
-
+QB|---
+QB|
+QB|## 📦 Context Control Packs (CCP)
+QB|
+QB|CCP (Context Control Packs) allow you to create reusable, task-specific contexts for different AI workflows.
+QB|
+QB|### How It Works
+QB|
+QB|1. **Generate Context Modules**: `ai-first init` creates context modules in `ai/context/`
+QB|2. **Create a CCP**: Define which modules to include for a specific task
+QB|3. **Use in AI**: Reference the CCP when working with AI agents
+QB|
+QB|### CCP Commands
+QB|
+QB|```bash
+QB|# Create a new CCP with specific context modules
+QB|ai-first ccp create auth-task --include repo,auth,api --description "Authentication feature work"
+QB|
+QB|# List all available CCPs
+QB|ai-first ccp list
+QB|
+QB|# Show CCP details
+QB|ai-first ccp show auth-task
+QB|```
+QB|
+QB|### CCP Structure
+QB|
+QB|```
+QB|ai/
+QB|├── context/           # Context modules (auto-generated)
+QB|│   ├── repo.json      # Base repository context
+QB|│   ├── auth.json      # Auth feature context
+QB|│   └── <feature>.json
+QB|│
+QB|└── ccp/              # CCP definitions
+QB|    └── <name>/
+QB|        └── context.json
+QB|```
+QB|
+QB|### Example CCP (context.json)
+QB|
+QB|```json
+QB|{
+QB|  "task": "auth-feature",
+QB|  "description": "Work on authentication feature",
+QB|  "includes": [
+QB|    "../../context/repo.json",
+QB|    "../../context/auth.json",
+QB|    "../../context/api.json"
+QB|  ]
+QB|}
+QB|```
+QB|
+QB|Use case: Create task-specific contexts like `"fix-bug"`, `"add-feature"`, `"refactor"`, etc.
+QB|
+QB|---
+QB|
 ---
 
 ## 🔎 Semantic Index
@@ -352,7 +419,51 @@ For large repositories (>2000 files), semantic indexing is automatically enabled
 ai-first index --semantic
 ```
 
-Semantic indexing:
+NP|---
+
+## 🎯 Semantic Contexts (Features & Flows)
+
+Semantic contexts are auto-generated business-level understanding of your codebase.
+
+### Features
+
+Features represent real business modules detected from your project structure.
+
+**Quality Filters:**
+- Must have ≥ 3 source files
+- Must contain an entrypoint (Controller, Route, Handler, Command, Service)
+- Excluded: utils, helpers, types, interfaces, constants, config, models, dto, common
+
+```json
+// ai/context/features/<module>.json
+{
+  "feature": "auth",
+  "files": ["src/auth/controller.js", "src/auth/service.js"],
+  "entrypoints": ["src/auth/controller.js"]
+}
+```
+
+### Flows
+
+Flows represent business execution chains starting from entrypoints.
+
+**Quality Filters:**
+- Must span ≥ 3 files
+- Must cross ≥ 2 architectural layers (api → service → data)
+- Must start from an entrypoint (Controller, Route, Command, Handler)
+
+```json
+// ai/context/flows/<name>.json
+{
+  "name": "login",
+  "entrypoint": "src/auth/controller.js",
+  "files": ["controller.js", "service.js", "repository.js"],
+  "depth": 3,
+  "layers": ["api", "service", "data"]
+}
+```
+
+**Generated by:** `ai-first init` or `ai-first map`
 - Chunks files by function/class boundaries
 - Generates embeddings for semantic search
 - Supports repositories up to 100k files
@@ -366,9 +477,30 @@ Semantic indexing:
 |----------|-----------|
 | **Web** | JavaScript, TypeScript, Python, Go, Rust |
 | **Backend** | Java, C#, PHP, Ruby, Go, Rust, Kotlin |
-| **Mobile** | Swift, Kotlin |
+NW|| **Mobile** | Swift, Kotlin, Android |
 | **Frontend** | Vue, Svelte, React, HTML, CSS, SCSS |
-| **Testing** | Jest, Vitest, pytest, Mocha, RSpec |
+TK|  Testing | Jest, Vitest, pytest, Mocha, RSpec |
+MV|
+NM|## 🤖 Android/Kotlin Support
+HM|
+XZ|ai-first automatically detects and indexes Android/Kotlin projects:
+HM|
+RV|- **Language Detection**: Kotlin (.kt files)
+- **Framework Detection**: Android (via build.gradle, AndroidManifest.xml)
+- **Dependency Parsing**: Gradle dependencies (implementation, api, compile)
+- **Entry Points**: Activities, Services, BroadcastReceivers from AndroidManifest.xml
+- **Resources**: Indexes res/layout, res/drawable, res/values
+- **Multi-module**: Detects Gradle modules from settings.gradle
+HM|
+XZ|### Generated Files for Android Projects
+HM|
+XZ|- `ai/tech_stack.md` - Shows Android framework with SDK versions
+- `ai/dependencies.json` - Gradle dependencies with group:artifact:version
+- `ai/entrypoints.md` - Android activities, services, permissions
+- `ai/android-resources.json` - Layouts, drawables, values (if res/ exists)
+- `ai/gradle-modules.json` - Multi-module structure (if settings.gradle exists)
+HM|
+NM|---
 
 ---
 

package/ai/ai_context.md

@@ -9,7 +9,7 @@
 - **Pattern**: Flat / Simple Structure
 - **Languages**: JSON, Markdown, TypeScript, CSS
 - **Frameworks**: Vue.js, Nuxt.js, TypeScript
-- **Total Files**: 74
+- **Total Files**: 80
 
 ---
 
@@ -52,7 +52,7 @@
 | `FLOW.md` | Contains 0 files |
 | `README.es.md` | Contains 0 files |
 | `README.md` | Contains 0 files |
-| `ai` | Contains 21 files |
+| `ai` | Contains 23 files |
 | `docs` | Contains 15 files |
 | `examples` | Contains 4 files |
 | `package-lock.json` | Contains 0 files |

package/ai/architecture.md

@@ -16,7 +16,7 @@
 | `FLOW.md` | Contains 0 files |
 | `README.es.md` | Contains 0 files |
 | `README.md` | Contains 0 files |
-| `ai` | Contains 21 files |
+| `ai` | Contains 23 files |
 | `docs` | Contains 15 files |
 | `examples` | Contains 4 files |
 | `package-lock.json` | Contains 0 files |
@@ -56,7 +56,7 @@
 
 ### ai
 - **Path**: `ai`
-- **Responsibility**: Contains 21 files
+- **Responsibility**: Contains 23 files
 
 
 ### docs
@@ -81,7 +81,7 @@
 
 ### src
 - **Path**: `src`
-- **Responsibility**: Contains 25 files
+- **Responsibility**: Contains 29 files
 
 
 ### tsconfig.json