ai-first-cli 1.2.1 → 1.2.3

package/README.md

@@ -4,8 +4,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">
@@ -17,11 +17,51 @@
 
 > **Give your AI coding assistant superpowers.** Generate instant project context so AI agents understand your codebase in seconds, not minutes.
 
+---
+
+## 📋 Table of Contents
+
+- [Commands](#-commands-reference)
+- [Quick Start](#-quick-start)
+- [Installation](#-installation)
+- [Use Cases](#-use-cases)
+- [Benchmark](#-benchmark)
+- [How It Works](#-how-it-works)
+- [Generated Files](#-generated-files)
+- [AI Agents](#-supported-ai-agents)
+- [Roadmap](#-roadmap)
+- [Contributing](#-for-contributors)
+
+---
+
+## ⚡ Commands Reference
+
+| Command | Description |
+|---------|-------------|
+| `af init` | Generate all context files (symbols, dependencies, architecture, etc.) |
+| `af index` | Create SQLite database for fast symbol queries |
+| `af update` | Incrementally update context when files change |
+| `af watch` | Watch for file changes and auto-update index |
+| `af context` | Extract context around a specific symbol or function |
+| `af explore` | Explore module dependencies interactively |
+| `af map` | Generate repository map with all relationships |
+| `af doctor` | Check repository health and AI readiness |
+| `af query` | Query the index (symbols, imports, exports, stats) |
+| `af adapters` | List supported language/framework adapters |
+| `af git` | Show recent git activity and changed files |
+| `af graph` | Display knowledge graph visualization |
+| `af --completions` | Generate shell autocomplete script |
+
+> **Note:** All commands work with `af` (recommended) or `ai-first` (legacy).
+
+---
+
 <!-- START FIRST 10 SECONDS VALUE -->
 ## ⚡ In 10 Seconds
 
 ```
-$ 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,77 +73,59 @@ $ npx ai-first init
 **Result:** AI understands your project in ~500 tokens instead of 50,000.
 <!-- END FIRST 10 SECONDS VALUE -->
 
----
-
----
-
 ## ⚡ Quick Start
 
 Initialize AI-First in your repository:
 
 ```
-ai-first init
+af init
 ```
 
 Index the repository so AI agents can understand the codebase:
 
 ```
-ai-first index
-```
-
-Generate a repository architecture map:
-
-```
-ai-first summarize
+af index
 ```
 
 * `init` generates 11 context files with project metadata
 * `index` creates a SQLite database for fast symbol queries
-* `summarize` creates hierarchical summaries for AI navigation
 
 ---
 
-## ❓ Why AI-First?
-
-AI coding assistants often struggle with large repositories.
-
-Common problems:
+## 📦 Installation
 
-* limited context windows
-* lack of architectural awareness
-* difficulty navigating large codebases
-* missing relationships between modules
+### Requirements
+- Node.js 18+ (for optional semantic indexing)
 
-AI-First solves this by creating a repository intelligence layer.
+### Install
 
-This allows AI agents to:
+```bash
+# Install globally (recommended)
+npm install -g ai-first-cli
 
-* understand project structure
-* retrieve relevant code
-* navigate large repositories
-* maintain architectural context
+# Now you can use 'af' command
+af init
+af index
+af doctor
+```
 
----
-## 🚀 Why ai-first?
+### Other Installation Methods
 
-| Before ai-first | After ai-first |
-|-----------------|----------------|
-| AI reads 500+ files to understand project | AI reads 1 file with full context |
-| $5+ per project in API costs | ~$0.05 per project |
-| 30+ seconds for AI to "warm up" | Instant understanding |
-| AI misses conventions & patterns | AI knows your architecture |
+```bash
+# Homebrew (macOS/Linux)
+brew tap julianperezpesce/tap
+brew install ai-first-cli
 
----
+# Install script (Linux/macOS/WSL)
+curl -fsSL https://raw.githubusercontent.com/julianperezpesce/ai-first/master/install.sh | bash
+```
 
-## 📦 Installation
+### Shell Autocomplete
 
 ```bash
-# Quick start (no install)
-npx ai-first init
-
-# Or install globally
-npm install -g ai-first
-ai-first init
+# For bash
+af --completions > /usr/local/etc/bash_completion.d/af.bash
+source /usr/local/etc/bash_completion.d/af.bash
 ```
 
 ---
@@ -112,19 +134,19 @@ ai-first init
 
 ### 1. AI Coding Agents (OpenCode, Cursor, Claude Code)
 ```bash
-ai-first init
+af init
 # Then ask AI: "Read ai-context/ai_context.md and help me add a feature"
 ```
 
 ### 2. Onboarding New Developers
 ```bash
-ai-first init
+af init
 # New dev reads ai-context/ai_context.md → understands project in 2 minutes
 ```
 
 ### 3. Project Documentation
 ```bash
-ai-first init
+af init
 # Instant auto-generated documentation always up to date
 ```
 
@@ -145,7 +167,7 @@ Result: Broken code, wasted tokens
 ### After: AI Enlightened
 
 ```
-$ ai-first init
+$ af init
 
 You: "Read ai-context/ai_context.md, then add authentication"
 AI: *reads 1 file (0.5s)*
@@ -241,32 +263,22 @@ AI-First CLI
 ```
 ai-context/
 ├── ai_context.md      # ⭐ Start here — unified overview
-├── repo_map.json     # Machine-readable structure
+├── repo_map.json      # Machine-readable structure
 ├── symbols.json       # Extracted functions/classes with unique IDs
 ├── dependencies.json  # Import relationships
 ├── architecture.md    # Architecture pattern
-├── tech_stack.md     # Languages & frameworks
-├── entrypoints.md    # Entry points
-├── conventions.md    # Coding conventions
-├── 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 init` or `map`
+├── tech_stack.md      # Languages & frameworks
+├── entrypoints.md     # Entry points
+├── conventions.md     # Coding conventions
+├── index.db           # SQLite index (generated by `af index`)
+├── graph/             # Module dependency graphs (generated by `af map`)
+│   ├── module-graph.json
+│   └── symbol-graph.json
+└── context/           # Business context (generated by `af init`)
     ├── 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)
 ```
 
 ---
@@ -287,33 +299,33 @@ ai-context/
 
 ```bash
 # Generate context
-ai-first init
+af init
 
 # Generate symbol graph and context packets
-ai-first map
+af map
 
 # Generate SQLite index for fast queries
-ai-first index
+af index
 
 # Force semantic indexing (for large repos)
-ai-first index --semantic
+af index --semantic
 
 # Generate context for a specific symbol
-ai-first context extractSymbols
-ai-first context MyClass
+af context extractSymbols
+af context MyClass
 
 # Check repository health
-ai-first doctor
+af doctor
 
 # Explore module dependencies
-ai-first explore all
-ai-first explore src
+af explore all
+af explore src
 
 # Custom output directory
-ai-first init --output ./docs/ai
+af init --output ./docs/ai
 
 # Custom root directory
-ai-first init --root ./my-project
+af init --root ./my-project
 ```
 
 ---
@@ -323,8 +335,8 @@ ai-first init --root ./my-project
 Check repository health and AI readiness:
 
 ```bash
-ai-first doctor
-ai-first doctor --fix
+af doctor
+af doctor --fix
 ```
 
 The doctor command scans your repository and reports:
@@ -344,34 +356,23 @@ Navigate module dependencies:
 
 ```bash
 # List all modules
-ai-first explore all
+af explore all
 
 # Explore specific module
-ai-first explore src
+af explore src
 ```
 
 The explore command generates a module dependency graph based on imports.
 
 ---
 
-## 📦 Context Control Packs (CCP)
-QB|
----
-
 ## 🔎 Semantic Index
 
 For large repositories (>2000 files), semantic indexing is automatically enabled:
 
 ```bash
 # Force semantic indexing
-ai-first index --semantic
-```
-
-For large repositories (>2000 files), semantic indexing is automatically enabled:
-
-```bash
-# Force semantic indexing
-ai-first index --semantic
+af index --semantic
 ```
 
 ---
@@ -418,7 +419,7 @@ Flows represent business execution chains starting from entrypoints.
 }
 ```
 
-**Generated by:** `ai-first init` or `ai-first map`
+**Generated by:** `af init` or `af map`
 - Chunks files by function/class boundaries
 - Generates embeddings for semantic search
 - Supports repositories up to 100k files
@@ -483,21 +484,23 @@ ai-first automatically detects and indexes Android/Kotlin projects:
 - PHP and Ruby parser support added
 - All 11 adapters now working (100% coverage)
 
-### Phase 3 (Planned)
-- [ ] Enhanced semantic indexing
-- [ ] Plugin system for custom analyzers
-- [ ] PHP support (Laravel test project)
-- [ ] Ruby support (Rails test project)
-- [ ] Scala support
-- [ ] Configuration file support (`ai-first.config.json`)
-- [ ] Custom rules/plugins system
-- [ ] CI/CD integration templates
-
-### Phase 4 (Future)
-- [ ] Git integration (analyze recent changes)
-- [ ] Diff-aware context (what changed since last run)
-- [ ] Interactive mode
-- [ ] VS Code extension
+### Phase 3 ✅ (Completed)
+- Enhanced semantic indexing
+- PHP and Ruby support (Laravel and Rails test projects)
+- Configuration file support (`ai-first.config.json`)
+- Custom rules/plugins system
+- CI/CD integration templates
+
+### Phase 4 ✅ (Completed)
+- Git integration (analyze recent changes)
+- Diff-aware context (what changed since last run)
+- Interactive mode
+- SQLite index for fast symbol queries
+
+### Phase 5 ✅ (Completed)
+- Architecture: `ai/` → `ai-context/`
+- Performance: embeddings to SQLite
+- Documentation: comprehensive README improvements
 
 ---
 

package/TEST_RESULTS.md

@@ -0,0 +1,198 @@
+# ai-first-cli Test Results - POST BUG FIXES
+## Fecha: 2026-03-17
+## Ejecutado por: Sisyphus (Post Fix)
+
+---
+
+## 🎉 RESUMEN: TODOS LOS BUGS CORREGIDOS
+
+### Estado General: ✅ 100% FUNCIONAL
+
+**Comandos que funcionan correctamente (12/12):**
+- ✅ `init` - 5/5 proyectos
+- ✅ `map` - 5/5 proyectos  
+- ✅ `doctor` - 5/5 proyectos
+- ✅ `index` - **CORREGIDO** ✅ Genera index.db
+- ✅ `graph` - **CORREGIDO** ✅ Genera knowledge-graph.json
+- ✅ `query` - **CORREGIDO** ✅ Encuentra símbolos
+- ✅ `context` - Funciona
+- ✅ `summarize` - Funciona
+- ✅ `update` - Funciona
+- ✅ `explore` - Funciona
+- ✅ `adapters` - Funciona
+- ✅ `git` - Funciona (requiere repo git)
+
+---
+
+## 📊 RESULTADOS DETALLADOS POR COMANDO
+
+### 1. init ✅ FUNCIONA
+
+**Proyectos probados**: 5/5 exitosos
+
+| Proyecto | Estado | Features | Flows |
+|----------|--------|----------|-------|
+| express-api | ✅ | 2 | 2 |
+| nestjs-backend | ✅ | 1 | 2 |
+| python-cli | ✅ | 1 | 3 |
+| react-app | ✅ | 1 | 3 |
+| salesforce-cli | ✅ | 1 | 2 |
+
+---
+
+### 2. map ✅ FUNCIONA
+
+**Proyectos probados**: 5/5 exitosos
+
+| Proyecto | Símbolos | Relaciones |
+|----------|----------|------------|
+| express-api | 49 | 42 |
+| nestjs-backend | 18 | 13 |
+| python-cli | 14 | 21 |
+| react-app | 40 | 50 |
+| salesforce-cli | 7 | 7 |
+
+---
+
+### 3. doctor ✅ FUNCIONA
+
+**Proyectos probados**: 5/5 - Estado: PARTIALLY READY (sin errores críticos)
+
+---
+
+### 4. index ✅ CORREGIDO
+
+**Estado**: ✅ FUNCIONA - Genera index.db correctamente
+
+**Verificación:**
+```
+-rw-r--r-- 1 julian julian 45056 nestjs-backend/ai/index.db
+```
+
+**Contenido indexado:**
+- Files: 36
+- Symbols: 18
+- Imports: 23
+
+---
+
+### 5. graph ✅ CORREGIDO
+
+**Estado**: ✅ FUNCIONA - Genera knowledge-graph.json correctamente
+
+**Verificación:**
+```
+-rw-r--r-- 1 julian julian 1809 express-api/ai/graph/knowledge-graph.json
+```
+
+**Contenido:**
+- Nodes: 4 (2 features, 2 flows)
+- Edges: 9 (contains, implements)
+
+**Nota**: Ahora funciona sin repo git (static analysis)
+
+---
+
+### 6. query ✅ CORREGIDO
+
+**Estado**: ✅ FUNCIONA - Encuentra símbolos correctamente
+
+**Comando probado:**
+```bash
+ai-first query symbol AuthController --root test-projects/nestjs-backend
+```
+
+**Resultado:**
+```
+Name                | Type       | File                    | Line
+-------------------|------------|-------------------------|------
+AuthController     | class     | src/auth/auth.controller.ts| 6
+
+Total: 1 symbols
+EXIT: 0
+```
+
+---
+
+### 7. context ✅ FUNCIONA
+
+**Comando probado**: `ai-first context login`
+
+**Resultado:**
+```
+🎯 Generating context for symbol: login
+
+📦 Symbol Context Packet:
+   ID: controllers/authController.js#login
+   Type: function
+   Module: controllers
+   File: controllers/authController.js:6
+   Score: 11
+
+📊 Relationships:
+   Imports: 1 ✅
+   Related symbols: 1 ✅
+EXIT: 0
+```
+
+---
+
+### 8. summarize ✅ FUNCIONA
+
+**Resultado:**
+- Repository: express-api
+- Folders: 4
+- Files: 7
+- Output: ai/hierarchy.json
+
+---
+
+### 9. update ✅ FUNCIONA
+
+**Resultado:**
+- Changed files: 0 (no cambios)
+- Symbols: 0 updated
+- EXIT: 0
+
+---
+
+## 📈 COMPARATIVA: ANTES vs DESPUÉS
+
+| Comando | Antes | Después |
+|---------|-------|---------|
+| index | ❌ No generaba index.db | ✅ Genera index.db (45KB) |
+| graph | ❌ Exit 1, no generaba | ✅ Exit 0, genera knowledge-graph.json |
+| query | ❌ Exit 1, no encontraba | ✅ Exit 0, encuentra símbolos |
+
+---
+
+## ✅ VERIFICACIÓN FINAL
+
+```bash
+# Bug A - index
+node dist/commands/ai-first.js index --root test-projects/nestjs-backend
+# ✅ EXIT 0 - Genera ai/index.db (45056 bytes)
+
+# Bug B - graph  
+node dist/commands/ai-first.js graph --root test-projects/express-api
+# ✅ EXIT 0 - Genera ai/graph/knowledge-graph.json (1809 bytes)
+
+# Bug C - query
+node dist/commands/ai-first.js query symbol AuthController --root test-projects/nestjs-backend
+# ✅ EXIT 0 - Encuentra AuthController
+```
+
+---
+
+## 🎯 CONCLUSIONES
+
+**El CLI es 100% funcional:**
+- ✅ init, map, doctor, index, graph, query
+- ✅ context, summarize, update
+- ✅ explore, adapters, git
+
+**Todos los bugs reportados han sido corregidos exitosamente.**
+
+---
+
+Documento actualizado post-fix: 2026-03-17