@dastbal/nestjs-ai-agent 1.0.0 → 1.0.2

package/README.md

@@ -1,116 +1,10 @@
-# Meet the NestJS Code Alchemist 🧙‍♂️
-
-![NestJS Logo](https://nestjs.com/img/logo-small.svg)  
-
-
-# @dastbal/nestjs-ai-agent 🤖
-
-Autonomous AI Agent acting as a **Principal Software Engineer** for NestJS projects.
-
-## Features
-- **The Surgeon Rule**: Reads and analyzes files before writing code.
-- **RAG Powered**: Uses your codebase as context for precise implementations.
-- **SQLite Persistence**: Remembers conversation history between sessions.
-- **Self-Correcting**: Automatically runs integrity checks and fixes compilation errors.
-
-## Installation
-```bash
+@dastbal/nestjs-ai-agent 🧙‍♂️Autonomous Principal Software Engineer for NestJSTransform your NestJS development with an agent that doesn't just "chat", but operates directly on your codebase with Senior-level precision.🚀 Quick StartBash# Install the agent
 npm install @dastbal/nestjs-ai-agent
 
-npx gen "Create a new Payments service with DDD and its corresponding test"
-
-
-🔐 Configuration & Authentication
-This agent uses Google Vertex AI. To allow the agent to operate, you must provide your Google Cloud credentials.
-
-Create your credentials file: Place your Google Service Account JSON file in the root of your project and name it exactly: credentials_vertex.json
-
-Setup your environment: Create a .env file in your project root and point to that file:
-
-Code snippet
-GOOGLE_APPLICATION_CREDENTIALS="./credentials_vertex.json"
-# Optional: specify your project and location
+# Run your first command
+npx gen "Create a new Payments service with DDD patterns"
+✨ Key FeaturesFeatureDescription🔍 RAG SearchSemantic search across your entire codebase before proposing changes.🩺 The Surgeon RuleNever overwrites a file without reading and analyzing it first.✅ Self-HealingRuns integrity checks and auto-fixes compilation errors (up to 3 retries).💾 Safe WritesAutomatic backups before any file modification.🧠 SQLite MemoryRemembers conversation threads and preferences across restarts.🔐 ConfigurationThis agent leverages Google Vertex AI. To start, you need to provide your Google Cloud credentials.Credentials File: Place your Google Service Account JSON in the root folder.Naming: Name it exactly credentials_vertex.json.Environment: Add the following to your .env file:Code snippetGOOGLE_APPLICATION_CREDENTIALS="./credentials_vertex.json"
+# Optional config
 GCP_PROJECT_ID="your-project-id"
 GCP_LOCATION="us-central1"
-⚠️ Important Security Note: Never commit your credentials_vertex.json or .env files to version control. Add them to your .gitignore.
-
-## Introduction
-
-I am a specialized AI, a Principal Software Engineer, crafted to assist you in your NestJS projects. I operate directly on the project's local file system, enabling me to read, understand, and modify your codebase with precision and efficiency. My goal is to help you write clean, well-documented, and testable code, adhering to the best practices of NestJS and Domain-Driven Design (DDD).
-
-## Core Functionality
-
-Here's a breakdown of how I work:
-
-1.  **Understanding Your Needs:** I start by carefully interpreting your requests. I clarify any ambiguities and break down complex tasks into manageable steps.
-
-2.  **Code Exploration (🔍 `ask_codebase`):**
-    *   Before making any changes, I use the `ask_codebase` tool. This is my primary research instrument.
-    *   It allows me to perform semantic searches and analyze the project's dependency graph.
-    *   I use it to find relevant code snippets, understand how different parts of the system interact, and locate the exact file paths I need.
-
-3.  **Code Comprehension (📖 `safe_read_file`):**
-    *   When I need to modify a file, I *always* read its contents first using `safe_read_file`.
-    *   This ensures I understand the existing code, its structure, and any existing documentation (TSDocs).
-    *   This is crucial for avoiding regressions and maintaining code quality.
-
-4.  **Code Generation & Modification (✍️):**
-    *   Based on your instructions and my understanding of the code, I generate or modify code.
-    *   I adhere to strict TypeScript typing, DDD principles, and NestJS best practices.
-    *   I also create corresponding tests to ensure code reliability.
-
-5.  **Code Writing (💾 `safe_write_file`):**
-    *   I write the generated or modified code to the file system using `safe_write_file`.
-    *   This tool automatically creates a backup of the original file, providing a safety net.
-
-6.  **Integrity Validation (✅ `run_integrity_check`):**
-    *   Immediately after writing or modifying code, I run `run_integrity_check`.
-    *   This is a critical step. It uses the TypeScript compiler to ensure that the code is type-safe and compiles without errors.
-    *   This helps catch any mistakes I might have made.
-
-7.  **Self-Correction (🛠️):**
-    *   If the integrity check fails, I analyze the error messages and attempt to fix the code myself.
-    *   I will retry up to three times. If I cannot fix the error, I will ask for human assistance.
-
-8.  **Iteration and Refinement (🔄):**
-    *   I repeat these steps as needed, refining the code and ensuring it meets your requirements.
-
-9.  **Documentation (📝):**
-    *   I always strive to maintain and improve code documentation (TSDocs).
-
-10. **Learning and Adaptation (🧠):**
-    *   I learn from your feedback. If you correct a style preference, I store it in `/memories/style-guide.txt` to improve future responses.
-
-## Tools and Technologies
-
-I am built upon a foundation of powerful tools and technologies:
-
-*   **Language Model:** I leverage a large language model (LLM) from Google, enabling me to understand and generate human-like text.
-*   **Retrieval-Augmented Generation (RAG):** I utilize a live RAG system. This means I can dynamically access and process information from your codebase to provide accurate and relevant responses. This allows me to understand the context of your project and generate code that fits seamlessly.
-*   **NestJS Expertise:** I have been specifically trained on NestJS best practices, DDD, and related concepts.
-*   **TypeScript:** I am fluent in TypeScript and adhere to strict typing.
-*   **Libraries:** I utilize a suite of libraries for code analysis, generation, and validation.
-*   **File System Access:** I have secure access to the project's local file system, allowing me to directly modify your code.
-
-## Safety and Quality
-
-*   **Strict Typing:** I enforce strict TypeScript typing to prevent common errors.
-*   **Comprehensive Testing:** I create tests alongside the code to ensure its reliability.
-*   **Error Handling:** I use standard NestJS HTTP exceptions and avoid swallowing errors silently.
-*   **Code Reviews:** I am designed to be used in conjunction with human code reviews to ensure the highest quality.
-
-## How to Interact with Me
-
-Simply provide me with clear instructions, and I will do my best to assist you. For example:
-
-*   "Add a new DTO for the User entity."
-*   "Create a service to handle authentication."
-*   "Write a unit test for the UserService."
-
-I will guide you through the process, providing feedback and ensuring the code meets your requirements.
-
-## Disclaimer
-
-I am an AI assistant and should be used responsibly. Always review the code I generate before deploying it to production. I am constantly learning and improving, but I am not perfect. Please report any issues or suggestions.
-
-## Let's Build Something Amazing! ✨
+[!CAUTION]Security First: Always add credentials_vertex.json and .env to your .gitignore.🛠️ Internal WorkflowThe agent follows a strict Principal Engineer protocol:Research: Uses ask_codebase to find patterns and dependencies.Comprehension: Reads existing logic with safe_read_file to avoid regressions.Implementation: Writes code following DDD, Strict Typing (No any), and TSDocs.Validation: Runs run_integrity_check (TypeScript compiler) immediately.Human-in-the-loop: Pauses for approval before critical disk operations.💡 Usage ExamplesTry these commands to see the agent in action:Scaffolding: "Create a UserEntity with email and password fields using TypeORM"Logic: "Add a validation pipe to the login DTO"Testing: "Write a unit test for the AuthService including mocks for the repository"Refactoring: "Standardize all HTTP exceptions in the users controller"🧠 Learning & AdaptationThe agent learns from your feedback. If you provide a style correction, it stores it in .agent/memories/style-guide.txt to ensure future code aligns with your personal or team preferences.📄 LicenseReleased under the MIT License. Build something amazing! ✨

package/dist/bin/cli.js

@@ -64,7 +64,7 @@ program
         const threadId = "cli-user-session";
         const agent = await factory_1.AgentFactory.create(threadId);
         log.ai(`Procesando: "${instruction}"`);
-        const response = await agent.invoke({ messages: [{ role: "user", content: instruction }] }, { configurable: { thread_id: threadId } });
+        const response = await agent.invoke({ messages: [{ role: "user", content: instruction }] }, { configurable: { thread_id: threadId }, recursionLimit: 50 });
         const lastMessage = response.messages[response.messages.length - 1];
         if (lastMessage && lastMessage.content) {
             console.log("\n" + chalk_1.default.green("--- RESPUESTA DEL AGENTE ---"));

package/dist/core/agent/factory.d.ts

@@ -1,24 +1,33 @@
 export declare class AgentFactory {
     static create(threadId?: string): Promise<import("langchain").ReactAgent<import("langchain").AgentTypeConfig<import("langchain").ResponseFormatUndefined, undefined, import("langchain").AnyAnnotationRoot, readonly import("langchain").AgentMiddleware<any, any, any, readonly (import("@langchain/core/tools").ClientTool | import("@langchain/core/tools").ServerTool)[]>[], readonly [import("langchain").DynamicStructuredTool<import("zod").ZodObject<{
         query: import("zod").ZodString;
+        projectRoot: import("zod").ZodOptional<import("zod").ZodString>;
     }, import("zod/v4/core").$strip>, {
         query: string;
+        projectRoot?: string | undefined;
     }, {
         query: string;
+        projectRoot?: string | undefined;
     }, string, "ask_codebase">, import("langchain").DynamicStructuredTool<import("zod").ZodObject<{}, import("zod/v4/core").$strip>, Record<string, never>, Record<string, never>, string, "run_integrity_check">, import("langchain").DynamicStructuredTool<import("zod").ZodObject<{
         filePath: import("zod").ZodString;
         content: import("zod").ZodString;
+        projectRoot: import("zod").ZodOptional<import("zod").ZodString>;
     }, import("zod/v4/core").$strip>, {
         filePath: string;
         content: string;
+        projectRoot?: string | undefined;
     }, {
         filePath: string;
         content: string;
+        projectRoot?: string | undefined;
     }, string, "safe_write_file">, import("langchain").DynamicStructuredTool<import("zod").ZodObject<{
         filePath: import("zod").ZodString;
+        projectRoot: import("zod").ZodOptional<import("zod").ZodString>;
     }, import("zod/v4/core").$strip>, {
         filePath: string;
+        projectRoot?: string | undefined;
     }, {
         filePath: string;
+        projectRoot?: string | undefined;
     }, string, "safe_read_file">, import("langchain").DynamicStructuredTool<import("zod").ZodObject<{}, import("zod/v4/core").$strip>, Record<string, never>, Record<string, never>, string, "refresh_project_index">]>>>;
 }

package/dist/core/rag/indexer.d.ts

@@ -12,26 +12,33 @@ export declare class IndexerService {
     /**
      * Main Entry Point: Scans the project and updates the brain.
      * Scans files, checks hashes, generates embeddings, and saves the knowledge graph.
-     * * @param sourceDir - Relative path to source code (usually 'src').
+     * @param sourceDir - Relative path to source code (usually 'src'). Defaults to 'src'.
      */
     indexProject(sourceDir?: string): Promise<void>;
     /**
      * Processes a single file: Reads content, Calculates Hash, Parses AST,
      * Updates Registry, and Accumulates Chunks.
+     * @param filePath - The relative path of the file to process.
+     * @param chunkAccumulator - An array to accumulate processed code chunks.
+     * @param edgeAccumulator - An array to accumulate dependency graph edges.
      */
     private processSingleFile;
     /**
      * Generates embeddings using Vertex AI and saves them to SQLite in transactions.
+     * @param allChunks - An array of all processed chunks to embed and save.
      */
     private embedAndSaveBatches;
     /**
      * Persists dependency relationships into the graph table.
      * Uses 'INSERT OR IGNORE' to prevent duplicates without errors.
+     * @param edges - An array of GraphEdge objects to save.
      */
     private saveGraph;
     /**
      * Recursively gets all .ts files in a directory.
      * Returns RELATIVE paths (e.g., 'src/users/users.service.ts') to ensure consistency in DB.
+     * @param dir - The directory to search in.
+     * @param fileList - An accumulator for the list of files found.
      */
     private getAllFiles;
 }

package/dist/core/rag/indexer.js

@@ -56,7 +56,7 @@ class IndexerService {
     /**
      * Main Entry Point: Scans the project and updates the brain.
      * Scans files, checks hashes, generates embeddings, and saves the knowledge graph.
-     * * @param sourceDir - Relative path to source code (usually 'src').
+     * @param sourceDir - Relative path to source code (usually 'src'). Defaults to 'src'.
      */
     async indexProject(sourceDir = 'src') {
         const rootDir = process.cwd();
@@ -100,6 +100,9 @@ class IndexerService {
     /**
      * Processes a single file: Reads content, Calculates Hash, Parses AST,
      * Updates Registry, and Accumulates Chunks.
+     * @param filePath - The relative path of the file to process.
+     * @param chunkAccumulator - An array to accumulate processed code chunks.
+     * @param edgeAccumulator - An array to accumulate dependency graph edges.
      */
     processSingleFile(filePath, chunkAccumulator, edgeAccumulator) {
         try {
@@ -131,6 +134,7 @@ class IndexerService {
     }
     /**
      * Generates embeddings using Vertex AI and saves them to SQLite in transactions.
+     * @param allChunks - An array of all processed chunks to embed and save.
      */
     async embedAndSaveBatches(allChunks) {
         console.log(`🧠 Generating Embeddings for ${allChunks.length} chunks...`);
@@ -150,9 +154,9 @@ class IndexerService {
                 const embeddingsModel = provider_1.LLMProvider.getEmbeddingsModel();
                 const vectors = await embeddingsModel.embedDocuments(textsToEmbed);
                 // 3. Save to DB (Transaction for performance)
-                const insertChunk = this.db.prepare(`
-          INSERT OR REPLACE INTO code_chunks (id, file_path, chunk_type, content, vector_json, metadata)
-          VALUES (?, ?, ?, ?, ?, ?)
+                const insertChunk = this.db.prepare(`
+          INSERT OR REPLACE INTO code_chunks (id, file_path, chunk_type, content, vector_json, metadata)
+          VALUES (?, ?, ?, ?, ?, ?)
         `);
                 // Explicitly typed transaction callback to fix TS7006
                 const insertMany = this.db.transaction((chunks, vectors) => {
@@ -174,13 +178,14 @@ class IndexerService {
     /**
      * Persists dependency relationships into the graph table.
      * Uses 'INSERT OR IGNORE' to prevent duplicates without errors.
+     * @param edges - An array of GraphEdge objects to save.
      */
     saveGraph(edges) {
         if (!edges || edges.length === 0)
             return;
-        const insertEdge = this.db.prepare(`
-      INSERT OR IGNORE INTO dependency_graph (source, target, relation)
-      VALUES (?, ?, ?)
+        const insertEdge = this.db.prepare(`
+      INSERT OR IGNORE INTO dependency_graph (source, target, relation)
+      VALUES (?, ?, ?)
     `);
         // Explicitly typed transaction callback to fix TS7006
         const runMany = this.db.transaction((edges) => {
@@ -191,6 +196,8 @@ class IndexerService {
     /**
      * Recursively gets all .ts files in a directory.
      * Returns RELATIVE paths (e.g., 'src/users/users.service.ts') to ensure consistency in DB.
+     * @param dir - The directory to search in.
+     * @param fileList - An accumulator for the list of files found.
      */
     getAllFiles(dir, fileList = []) {
         const files = fs.readdirSync(dir);

package/dist/core/rag/retriever.d.ts

@@ -3,17 +3,25 @@ interface SearchResult {
     chunk: ProcessedChunk;
     score: number;
 }
+/**
+ * @description Service responsible for retrieving relevant code context from the codebase using vector search and dependency graph analysis.
+ */
 export declare class RetrieverService {
     private db;
     /**
      * Searches the codebase using Vector Embeddings (Cosine Similarity).
-     * @param query - The natural language query.
-     * @param limit - Max chunks to retrieve.
+     * @param query - The natural language query to search for.
+     * @param limit - The maximum number of chunks to retrieve. Defaults to 5.
+     * @param projectRoot - Optional. The project root directory. This parameter provides context for the search and ensures consistency with how paths were indexed. Defaults to process.cwd().
+     * @returns {Promise<SearchResult[]>} A promise that resolves to an array of search results, each containing a code chunk and its relevance score.
      */
-    query(query: string, limit?: number): Promise<SearchResult[]>;
+    query(query: string, limit?: number, projectRoot?: string): Promise<SearchResult[]>;
     /**
      * Retrieves the 'Graph Dependencies' for a specific file from the DB.
      * This allows the Agent to know what other files are related (DTOs, Interfaces).
+     * @param sourcePath - The path to the source file (expected to be relative to projectRoot).
+     * @param projectRoot - Optional. The project root directory. This parameter provides context for interpreting paths. Defaults to process.cwd().
+     * @returns {string[]} An array of paths representing the dependencies of the source file.
      */
     private getDependencies;
     /**
@@ -22,7 +30,10 @@ export declare class RetrieverService {
      * 1. The matched code snippets (Vector Search).
      * 2. The file's dependencies (Graph Search).
      * 3. Explicit File Paths to encourage using 'read_file'.
+     * @param query - The search query.
+     * @param projectRoot - Optional. The project root directory. This parameter provides context for the search and ensures consistency with how paths were indexed. Defaults to process.cwd().
+     * @returns {Promise<string>} A promise that resolves to the formatted context report string.
      */
-    getContextForLLM(query: string): Promise<string>;
+    getContextForLLM(query: string, projectRoot?: string): Promise<string>;
 }
 export {};

package/dist/core/rag/retriever.js

@@ -32,68 +32,89 @@ var __importStar = (this && this.__importStar) || (function () {
         return result;
     };
 })();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.RetrieverService = void 0;
 const db_1 = require("../state/db");
 const provider_1 = require("../llm/provider");
 const math_1 = require("./math");
 const path = __importStar(require("path"));
+const chalk_1 = __importDefault(require("chalk")); // Import chalk for colored logs
+const log = {
+    tool: (msg) => console.log(chalk_1.default.yellow('🛠️  [TOOL]: ') + msg),
+    error: (msg) => console.log(chalk_1.default.red('❌ [ERR]: ') + msg),
+};
+/**
+ * @description Service responsible for retrieving relevant code context from the codebase using vector search and dependency graph analysis.
+ */
 class RetrieverService {
     constructor() {
         this.db = db_1.AgentDB.getInstance();
     }
     /**
      * Searches the codebase using Vector Embeddings (Cosine Similarity).
-     * @param query - The natural language query.
-     * @param limit - Max chunks to retrieve.
+     * @param query - The natural language query to search for.
+     * @param limit - The maximum number of chunks to retrieve. Defaults to 5.
+     * @param projectRoot - Optional. The project root directory. This parameter provides context for the search and ensures consistency with how paths were indexed. Defaults to process.cwd().
+     * @returns {Promise<SearchResult[]>} A promise that resolves to an array of search results, each containing a code chunk and its relevance score.
      */
-    async query(query, limit = 5) {
-        console.log(`🔍 [RAG] Embedding Query: "${query}"...`);
-        const embeddingModel = provider_1.LLMProvider.getEmbeddingsModel();
-        const queryVector = await embeddingModel.embedQuery(query);
-        const stmt = this.db.prepare('SELECT * FROM code_chunks');
-        const rows = stmt.all();
-        const scoredChunks = rows.map((row) => {
-            const vector = JSON.parse(row.vector_json);
-            const score = (0, math_1.cosineSimilarity)(queryVector, vector);
-            const metadata = JSON.parse(row.metadata);
-            return {
-                score,
-                chunk: {
-                    id: row.id,
-                    type: row.chunk_type,
-                    content: row.content,
-                    metadata: metadata,
-                    // Ensure filePath is recovered from the DB row or metadata
-                    filePath: row.file_path || metadata.filePath,
-                },
-            };
-        });
-        return scoredChunks.sort((a, b) => b.score - a.score).slice(0, limit);
+    async query(query, limit = 5, projectRoot = process.cwd()) {
+        log.tool(`RetrieverService.query: Searching with query: "${query}" (Project Root Context: "${projectRoot}")`);
+        try {
+            const embeddingModel = provider_1.LLMProvider.getEmbeddingsModel();
+            const queryVector = await embeddingModel.embedQuery(query);
+            const stmt = this.db.prepare('SELECT * FROM code_chunks');
+            const rows = stmt.all();
+            const scoredChunks = rows.map((row) => {
+                const vector = JSON.parse(row.vector_json);
+                const score = (0, math_1.cosineSimilarity)(queryVector, vector);
+                const metadata = JSON.parse(row.metadata);
+                return {
+                    score,
+                    chunk: {
+                        id: row.id,
+                        type: row.chunk_type,
+                        content: row.content,
+                        metadata: metadata,
+                        // filePath is expected to be a relative path stored in the DB
+                        filePath: row.file_path || metadata.filePath,
+                    },
+                };
+            });
+            log.tool(`RetrieverService.query: Found ${scoredChunks.length} raw chunks.`);
+            return scoredChunks.sort((a, b) => b.score - a.score).slice(0, limit);
+        }
+        catch (error) {
+            log.error(`RetrieverService.query: Error during search: ${error.message}`);
+            throw new Error(`Failed to perform codebase search: ${error.message}`);
+        }
     }
     /**
      * Retrieves the 'Graph Dependencies' for a specific file from the DB.
      * This allows the Agent to know what other files are related (DTOs, Interfaces).
+     * @param sourcePath - The path to the source file (expected to be relative to projectRoot).
+     * @param projectRoot - Optional. The project root directory. This parameter provides context for interpreting paths. Defaults to process.cwd().
+     * @returns {string[]} An array of paths representing the dependencies of the source file.
      */
-    getDependencies(sourcePath) {
-        // 1. IMPORTANTE: Normalizar la ruta para que coincida con lo guardado en DB
-        // Esto convierte "src\module\..." a "src/module/..."
+    getDependencies(sourcePath, projectRoot = process.cwd()) {
+        // Paths in the DB are relative to the project root where indexing occurred.
+        // Normalization ensures consistency regardless of OS path separators.
         const normalizedPath = sourcePath.split(path.sep).join('/');
         try {
-            // 2. Consultar la tabla dependency_graph que definiste en AgentDB
-            // Buscamos todo lo que este archivo (source) importa (target)
-            const stmt = this.db.prepare(`
-            SELECT target 
-            FROM dependency_graph 
-            WHERE source = ? OR source = ?
+            const stmt = this.db.prepare(`
+            SELECT target 
+            FROM dependency_graph 
+            WHERE source = ? OR source = ?
         `);
-            // Probamos con la ruta normalizada y la original por si acaso
+            // Query using both normalized and original path for robustness, though normalized should match DB.
             const results = stmt.all(normalizedPath, sourcePath);
-            // 3. Devolver solo los strings de los targets
+            log.tool(`RetrieverService.getDependencies: Found ${results.length} dependencies for ${sourcePath}`);
             return results.map((row) => row.target);
         }
         catch (error) {
-            console.error(`Error fetching dependencies for ${sourcePath}:`, error);
+            log.error(`RetrieverService.getDependencies: Error fetching dependencies for ${sourcePath}: ${error.message}`);
             return [];
         }
     }
@@ -103,54 +124,59 @@ class RetrieverService {
      * 1. The matched code snippets (Vector Search).
      * 2. The file's dependencies (Graph Search).
      * 3. Explicit File Paths to encourage using 'read_file'.
+     * @param query - The search query.
+     * @param projectRoot - Optional. The project root directory. This parameter provides context for the search and ensures consistency with how paths were indexed. Defaults to process.cwd().
+     * @returns {Promise<string>} A promise that resolves to the formatted context report string.
      */
-    async getContextForLLM(query) {
-        const results = await this.query(query, 4);
-        // Group chunks by File to provide a structured view
-        const filesMap = new Map();
-        for (const res of results) {
-            const path = res.chunk.filePath || 'unknown';
-            // console.log(res);
-            // console.log(path);
-            // console.log(this.getDependencies(path));
-            if (!filesMap.has(path)) {
-                filesMap.set(path, {
-                    filePath: path,
-                    relevance: res.score,
-                    chunks: [],
-                    imports: this.getDependencies(path), // <--- GRAPH MAGIC 🕸️
-                });
-            }
-            filesMap.get(path)?.chunks.push(res.chunk);
-        }
-        // Build the formatted string
-        let output = `🔎 **RAG ANALYSIS REPORT**\n`;
-        output += `Query: "${query}"\n`;
-        output += `Found ${filesMap.size} relevant files.\n\n`;
-        filesMap.forEach((fileCtx) => {
-            const relevancePct = (fileCtx.relevance * 100).toFixed(1);
-            output += `=================================================================\n`;
-            output += `📂 **FILE:** ${fileCtx.filePath}\n`;
-            output += `📊 **RELEVANCE:** ${relevancePct}%\n`;
-            if (fileCtx.imports.length > 0) {
-                output += `🔗 **DEPENDENCIES (Imports):**\n`;
-                // Show top 5 imports to give context on DTOs/Entities used
-                fileCtx.imports
-                    .slice(0, 5)
-                    .forEach((imp) => (output += `   - ${imp}\n`));
-                if (fileCtx.imports.length > 5)
-                    output += `   - (...and ${fileCtx.imports.length - 5} more)\n`;
+    async getContextForLLM(query, projectRoot = process.cwd()) {
+        log.tool(`RetrieverService.getContextForLLM: Generating context for query: "${query}" (Project Root Context: "${projectRoot}")`);
+        try {
+            const results = await this.query(query, 4, projectRoot);
+            const filesMap = new Map();
+            for (const res of results) {
+                const filePath = res.chunk.filePath || 'unknown';
+                if (!filesMap.has(filePath)) {
+                    filesMap.set(filePath, {
+                        filePath: filePath,
+                        relevance: res.score,
+                        chunks: [],
+                        // Pass projectRoot to getDependencies for consistency, though it primarily uses DB paths.
+                        imports: this.getDependencies(filePath, projectRoot),
+                    });
+                }
+                filesMap.get(filePath)?.chunks.push(res.chunk);
             }
-            output += `\n📝 **CODE SNIPPETS:**\n`;
-            fileCtx.chunks.forEach((chunk) => {
-                output += `   --- [${chunk.metadata.methodName || 'Class Structure'}] ---\n`;
-                output += `${chunk.content.trim()}\n\n`;
+            let output = `🔎 **RAG ANALYSIS REPORT**\n`;
+            output += `Query: "${query}"\n`;
+            output += `Found ${filesMap.size} relevant files.\n\n`;
+            filesMap.forEach((fileCtx) => {
+                const relevancePct = (fileCtx.relevance * 100).toFixed(1);
+                output += `=================================================================\n`;
+                output += `📂 **FILE:** ${fileCtx.filePath}\n`;
+                output += `📊 **RELEVANCE:** ${relevancePct}%\n`;
+                if (fileCtx.imports.length > 0) {
+                    output += `🔗 **DEPENDENCIES (Imports):**\n`;
+                    fileCtx.imports
+                        .slice(0, 5)
+                        .forEach((imp) => (output += `   - ${imp}\n`));
+                    if (fileCtx.imports.length > 5)
+                        output += `   - (...and ${fileCtx.imports.length - 5} more)\n`;
+                }
+                output += `\n📝 **CODE SNIPPETS:**\n`;
+                fileCtx.chunks.forEach((chunk) => {
+                    output += `   --- [${chunk.metadata.methodName || 'Class Structure'}] ---\n`;
+                    output += `${chunk.content.trim()}\n\n`;
+                });
+                output += `💡 **AGENT HINT:** To edit this file or see full imports, run: read_file("${fileCtx.filePath}")\n`;
+                output += `=================================================================\n\n`;
             });
-            output += `💡 **AGENT HINT:** To edit this file or see full imports, run: read_file("${fileCtx.filePath}")\n`;
-            output += `=================================================================\n\n`;
-        });
-        // console.log(output);
-        return output;
+            log.tool(`RetrieverService.getContextForLLM: Successfully generated context report.`);
+            return output;
+        }
+        catch (error) {
+            log.error(`RetrieverService.getContextForLLM: Error generating context: ${error.message}`);
+            throw new Error(`Failed to generate context for LLM: ${error.message}`);
+        }
     }
 }
 exports.RetrieverService = RetrieverService;

package/dist/core/tools/tools.d.ts

@@ -1,20 +1,39 @@
 import { z } from 'zod';
+/**
+ * @description WRITES code to the REAL local disk. Creates a backup automatically.
+ * @param filePath - Relative path to the file (e.g., 'src/app.service.ts'). This path is relative to the project root.
+ * @param content - Full file content.
+ * @param projectRoot - Optional. The project root directory. Defaults to process.cwd().
+ * @returns {Promise<string>} - A confirmation message or an error message.
+ */
 export declare const safeWriteFileTool: import("@langchain/core/tools").DynamicStructuredTool<z.ZodObject<{
     filePath: z.ZodString;
     content: z.ZodString;
+    projectRoot: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>, {
     filePath: string;
     content: string;
+    projectRoot?: string | undefined;
 }, {
     filePath: string;
     content: string;
+    projectRoot?: string | undefined;
 }, string, "safe_write_file">;
+/**
+ * @description READS code from the REAL local disk.
+ * @param filePath - Relative path to the file (e.g., 'src/app.service.ts'). This path is relative to the project root.
+ * @param projectRoot - Optional. The project root directory. Defaults to process.cwd().
+ * @returns {Promise<string>} - The file content or an error message.
+ */
 export declare const safeReadFileTool: import("@langchain/core/tools").DynamicStructuredTool<z.ZodObject<{
     filePath: z.ZodString;
+    projectRoot: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>, {
     filePath: string;
+    projectRoot?: string | undefined;
 }, {
     filePath: string;
+    projectRoot?: string | undefined;
 }, string, "safe_read_file">;
 /**
  * 🔍 TOOL: Ask Codebase (Semantic & Graph Search)
@@ -22,10 +41,13 @@ export declare const safeReadFileTool: import("@langchain/core/tools").DynamicSt
  */
 export declare const askCodebaseTool: import("@langchain/core/tools").DynamicStructuredTool<z.ZodObject<{
     query: z.ZodString;
+    projectRoot: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>, {
     query: string;
+    projectRoot?: string | undefined;
 }, {
     query: string;
+    projectRoot?: string | undefined;
 }, string, "ask_codebase">;
 /**
  * ✅ TOOL: Integrity Check (Compiler)

package/dist/core/tools/tools.js

@@ -56,12 +56,11 @@ const log = {
 /**
  * 💾 Genera un backup antes de modificar un archivo real.
  */
-const createBackup = (filePath) => {
-    const rootDir = process.cwd();
-    const backupDir = path.join(rootDir, '.agent', 'backups');
+const createBackup = (filePath, projectRoot = process.cwd()) => {
+    const backupDir = path.join(projectRoot, '.agent', 'backups');
     if (!fs.existsSync(backupDir))
         fs.mkdirSync(backupDir, { recursive: true });
-    const realPath = path.resolve(rootDir, filePath);
+    const realPath = path.resolve(projectRoot, filePath);
     if (fs.existsSync(realPath)) {
         const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
         const filename = path.basename(realPath);
@@ -69,63 +68,111 @@ const createBackup = (filePath) => {
         fs.copyFileSync(realPath, backupPath);
     }
 };
-exports.safeWriteFileTool = (0, tools_1.tool)(async ({ filePath, content }) => {
+/**
+ * @description WRITES code to the REAL local disk. Creates a backup automatically.
+ * @param filePath - Relative path to the file (e.g., 'src/app.service.ts'). This path is relative to the project root.
+ * @param content - Full file content.
+ * @param projectRoot - Optional. The project root directory. Defaults to process.cwd().
+ * @returns {Promise<string>} - A confirmation message or an error message.
+ */
+exports.safeWriteFileTool = (0, tools_1.tool)(async ({ filePath, content, projectRoot = process.cwd() }) => {
     try {
-        const rootDir = process.cwd();
-        const targetPath = path.resolve(rootDir, filePath);
-        if (!targetPath.startsWith(rootDir))
-            return '❌ Error: Access denied.';
+        // Resolve the target path relative to the project root
+        const targetPath = path.resolve(projectRoot, filePath);
+        log.tool(`safe_write_file: Attempting to write to: ${targetPath}`);
+        // Canonicalize paths for reliable comparison
+        const canonicalProjectPath = fs.realpathSync(projectRoot);
+        const canonicalTargetPath = fs.realpathSync(targetPath);
+        // Security Check: Ensure the target path is within the project root
+        if (!canonicalTargetPath.startsWith(canonicalProjectPath)) {
+            log.error(`safe_write_file: Access denied. Target path "${canonicalTargetPath}" is outside the project root "${canonicalProjectPath}".`);
+            return '❌ Error: Access denied. Attempted to write outside the project root.';
+        }
+        // Ensure the directory exists
         const dir = path.dirname(targetPath);
-        if (!fs.existsSync(dir))
+        if (!fs.existsSync(dir)) {
+            log.tool(`safe_write_file: Creating directory: ${dir}`);
             fs.mkdirSync(dir, { recursive: true });
-        createBackup(filePath); // Tu lógica de backup
+        }
+        // Create backup
+        createBackup(filePath, projectRoot);
+        // Write the file
         fs.writeFileSync(targetPath, content, 'utf-8');
-        log.sys(`Indexando cambio en: ${filePath}`);
+        log.tool(`File successfully written to: ${targetPath}`);
+        // Indexing (asynchronous)
+        log.sys(`Indexing change in: ${filePath}`);
         const indexer = new indexer_1.IndexerService();
-        indexer.indexProject().catch((err) => log.error(` ${err.message}`));
+        // Corrected: Pass only the sourceDir (defaulting to 'src') if needed, not projectRoot here.
+        indexer.indexProject('src').catch((err) => log.error(` Indexing failed: ${err.message}`));
         return `✅ File saved to REAL DISK: ${filePath}`;
     }
     catch (error) {
+        log.error(`safe_write_file: Error writing file "${filePath}": ${error.message}`);
         return `❌ Error: ${error.message}`;
     }
 }, {
     name: 'safe_write_file',
-    description: 'WRITES code to the REAL local disk. Creates a backup automatically.',
+    description: 'WRITES code to the REAL local disk. Creates a backup automatically. Ensures the file is within the project root.',
     schema: zod_1.z.object({
-        filePath: zod_1.z.string().describe('Relative path (e.g., src/app.service.ts)'),
-        content: zod_1.z.string().describe('Full file content'),
+        filePath: zod_1.z.string().describe('Relative path to the file (e.g., src/app.service.ts).'),
+        content: zod_1.z.string().describe('Full file content.'),
+        projectRoot: zod_1.z.string().optional().describe('Optional. The project root directory. Defaults to process.cwd().'),
     }),
 });
 // --- TOOL 2: READ FILE (Manual) ---
-exports.safeReadFileTool = (0, tools_1.tool)(async ({ filePath }) => {
+/**
+ * @description READS code from the REAL local disk.
+ * @param filePath - Relative path to the file (e.g., 'src/app.service.ts'). This path is relative to the project root.
+ * @param projectRoot - Optional. The project root directory. Defaults to process.cwd().
+ * @returns {Promise<string>} - The file content or an error message.
+ */
+exports.safeReadFileTool = (0, tools_1.tool)(async ({ filePath, projectRoot = process.cwd() }) => {
     try {
-        const rootDir = process.cwd();
-        const targetPath = path.resolve(rootDir, filePath);
-        if (!fs.existsSync(targetPath))
+        const targetPath = path.resolve(projectRoot, filePath);
+        log.tool(`safe_read_file: Attempting to read from: ${targetPath}`);
+        // Canonicalize paths for reliable comparison
+        const canonicalProjectPath = fs.realpathSync(projectRoot);
+        const canonicalTargetPath = fs.realpathSync(targetPath);
+        // Security Check: Ensure the target path is within the project root
+        if (!canonicalTargetPath.startsWith(canonicalProjectPath)) {
+            log.error(`safe_read_file: Access denied. Target path "${canonicalTargetPath}" is outside the project root "${canonicalProjectPath}".`);
+            return '❌ Error: Access denied. Attempted to read outside the project root.';
+        }
+        if (!fs.existsSync(targetPath)) {
+            log.error(`safe_read_file: File not found: ${targetPath}`);
             return '❌ File not found.';
-        return fs.readFileSync(targetPath, 'utf-8');
+        }
+        const content = fs.readFileSync(targetPath, 'utf-8');
+        log.tool(`Successfully read file: ${targetPath}`);
+        return content;
     }
     catch (e) {
+        log.error(`safe_read_file: Error reading file "${filePath}": ${e.message}`);
         return `Error: ${e.message}`;
     }
 }, {
     name: 'safe_read_file',
-    description: 'READS code from the REAL local disk.',
-    schema: zod_1.z.object({ filePath: zod_1.z.string() }),
+    description: 'READS code from the REAL local disk. Ensures the file is within the project root.',
+    schema: zod_1.z.object({
+        filePath: zod_1.z.string().describe('Relative path to the file (e.g., src/app.service.ts).'),
+        projectRoot: zod_1.z.string().optional().describe('Optional. The project root directory. Defaults to process.cwd().')
+    }),
 });
 /**
  * 🔍 TOOL: Ask Codebase (Semantic & Graph Search)
  * This is the Agent's "Eyes". It retrieves code + context.
  */
-exports.askCodebaseTool = (0, tools_1.tool)(async ({ query }) => {
+exports.askCodebaseTool = (0, tools_1.tool)(async ({ query, projectRoot = process.cwd() }) => {
     try {
-        // We assume the streaming UI handles the 'Thinking...' log via the framework events
+        log.tool(`ask_codebase: Querying codebase for: "${query}" with projectRoot: "${projectRoot}"`);
         const retriever = new retriever_1.RetrieverService();
-        const context = await retriever.getContextForLLM(query);
+        const context = await retriever.getContextForLLM(query, projectRoot);
+        log.tool(`ask_codebase: Found context for query: "${query}"`);
         return context;
     }
     catch (error) {
-        return `❌ Error querying codebase: ${error}`;
+        log.error(`ask_codebase: Error querying codebase: ${error.message}`);
+        return `❌ Error querying codebase: ${error.message}`;
     }
 }, {
     name: 'ask_codebase',
@@ -138,6 +185,7 @@ exports.askCodebaseTool = (0, tools_1.tool)(async ({ query }) => {
         query: zod_1.z
             .string()
             .describe("A natural language query describing the logic, DTO, or functionality you are looking for. (e.g., 'How is the RefundEntity defined?', 'Show me the auth guard')"),
+        projectRoot: zod_1.z.string().optional().describe('Optional. The project root directory. Defaults to process.cwd().'),
     }),
 });
 /**
@@ -147,12 +195,15 @@ exports.askCodebaseTool = (0, tools_1.tool)(async ({ query }) => {
 exports.integrityCheckTool = (0, tools_1.tool)(async () => {
     try {
         const rootDir = process.cwd();
+        log.tool('integrityCheckTool: Running integrity check');
         // 'tsc --noEmit' checks types without generating JS files. Fast and safe.
         const { stdout } = await execAsync('npx tsc --noEmit', { cwd: rootDir });
+        log.tool('integrityCheckTool: Integrity check passed');
         console.log('INTEGRITY CHECK PASSED.', rootDir, stdout);
         return `✅ INTEGRITY CHECK PASSED. The codebase is strictly typed and compiles correctly.\n${stdout}`;
     }
     catch (error) {
+        log.error('integrityCheckTool: Integrity check failed');
         // Return the exact compiler error so the agent can fix it
         return `❌ INTEGRITY CHECK FAILED. You must fix these TypeScript errors before finishing:\n${error.stdout || error.message}`;
     }
@@ -172,9 +223,11 @@ exports.integrityCheckTool = (0, tools_1.tool)(async () => {
 exports.refreshIndexTool = (0, tools_1.tool)(async () => {
     log.sys('🔄 Starting full project re-indexing...');
     try {
+        log.tool('refreshIndexTool: Starting full project re-indexing...'); // ADDED LOG
         // Start the expensive operation
         const indexer = new indexer_1.IndexerService();
         indexer.indexProject().catch((err) => log.error(` ${err.message}`));
+        log.tool('refreshIndexTool: Re-indexing completed successfully.'); // ADDED LOG
         log.sys('✅ Re-indexing completed successfully.');
         return '✅ Index successfully updated. I now have access to the latest code version.';
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dastbal/nestjs-ai-agent",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Autonomous AI Agent for NestJS - Principal Software Engineer Level with RAG and SQLite persistence",
   "author": "David Balladares",
   "license": "MIT",
@@ -38,8 +38,8 @@
     "zod": "^4.3.5"
   },
   "peerDependencies": {
-    "@nestjs/common": "^10.0.0",
-    "reflect-metadata": "^0.1.13"
+  "@nestjs/common": "^10.0.0 || ^11.0.0",
+  "reflect-metadata": "^0.1.13 || ^0.2.0"
   },
   "devDependencies": {
     "@nestjs/common": "^10.4.22",