@dastbal/nestjs-ai-agent 1.0.1 → 1.0.3

package/README.md

@@ -1,116 +1,79 @@
-# Meet the NestJS Code Alchemist 🧙‍♂️
+# @dastbal/nestjs-ai-agent 🧙‍♂️
+### Autonomous Principal Software Engineer for NestJS
 
-![NestJS Logo](https://nestjs.com/img/logo-small.svg)  
+[![npm version](https://img.shields.io/npm/v/@dastbal/nestjs-ai-agent.svg)](https://www.npmjs.com/package/@dastbal/nestjs-ai-agent)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
+Transform your NestJS development with an agent that doesn't just "chat", but **operates** directly on your codebase with Senior-level precision.
 
-# @dastbal/nestjs-ai-agent 🤖
+---
 
-Autonomous AI Agent acting as a **Principal Software Engineer** for NestJS projects.
+## 🚀 Quick Start
 
-## 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
+# 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
-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.
+# Run your first command
+npx gen "Create a new Payments service with DDD patterns"
+```
 
-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.
+## 💎 Key Features
 
-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.
+This agent operates with a strict set of principles and advanced capabilities:
 
-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.
+*   **🔍 RAG Search:** Performs semantic search across your entire codebase before proposing changes, ensuring context-aware development.
+*   **🩺 The Surgeon Rule:** Never overwrites a file without reading and analyzing it first, preserving existing logic and intent.
+*   **✅ Self-Healing:** Runs integrity checks (TypeScript compiler) and attempts to auto-fix compilation errors (up to 3 retries).
+*   **💾 Safe Writes:** Automatically creates backups before any file modification, ensuring data safety.
+*   **🧠 SQLite Memory:** Remembers conversation threads and learned preferences across restarts using a local SQLite database.
+*   **🔐 Configuration:** Leverages Google Vertex AI. Requires a service account JSON file (`credentials_vertex.json`) in the root folder and specific environment variables.
 
-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.
+    **Credentials File:** Place your Google Service Account JSON in the root folder and name it exactly `credentials_vertex.json`.
 
-8.  **Iteration and Refinement (🔄):**
-    *   I repeat these steps as needed, refining the code and ensuring it meets your requirements.
+    **Environment Variables:** Add the following to your `.env` file:
+    ```dotenv
+    GOOGLE_APPLICATION_CREDENTIALS="./credentials_vertex.json"
+    GCP_PROJECT_ID="your-project-id"
+    GCP_LOCATION="us-central1"
+    ```
+    **[CAUTION] Security First:** Always add `credentials_vertex.json` and `.env` to your `.gitignore` file to protect your credentials.
 
-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.
+## ⚙️ Internal Workflow
 
-## Tools and Technologies
+The agent follows a strict Principal Engineer protocol:
 
-I am built upon a foundation of powerful tools and technologies:
+1.  **Research:** Uses `ask_codebase` to find existing patterns, logic, and dependencies.
+2.  **Comprehension:** Reads existing code using `safe_read_file` to understand context and avoid regressions.
+3.  **Implementation:** Writes new code adhering to DDD principles, strict TypeScript typing (no `any`), and TSDocs.
+4.  **Validation:** Runs `run_integrity_check` (TypeScript compiler) immediately after implementation to ensure type safety.
+5.  **Safety:** Creates backups before writing files using `safe_write_file`.
+6.  **Human-in-the-loop:** Pauses for explicit approval before performing critical file operations or major changes.
 
-*   **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
+## 💡 Usage Examples
 
-*   **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.
+Try these commands to see the agent in action:
 
-## How to Interact with Me
+*   **Scaffolding:** `"Create a UserEntity with email and password fields using TypeORM"`
+*   **Logic Implementation:** `"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"`
+*   **Code Generation:** `"Generate a NestJS module for handling user authentication"`
 
-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."
+## 🧠 Learning & Adaptation
 
-I will guide you through the process, providing feedback and ensuring the code meets your requirements.
+The agent learns from your feedback. If you provide a style correction or a new pattern, it stores this information in `.agent/memories/style-guide.txt` to ensure future code generation aligns with your preferences.
 
-## 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.
+## 📄 License
 
-## Let's Build Something Amazing! ✨
+This project is released under the MIT License. Build something amazing! ✨

package/dist/bin/cli.js

@@ -61,10 +61,10 @@ program
         }
         log.sys("Inicializando Agente en modo CLI...");
         // El threadId puede ser fijo para sesiones de CLI o dinámico
-        const threadId = "cli-user-session";
+        const threadId = "cli-user";
         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.js

@@ -42,14 +42,14 @@ const tools_1 = require("../tools/tools");
 const path = __importStar(require("path"));
 const fs = __importStar(require("fs"));
 class AgentFactory {
-    static async create(threadId = 'cli-session') {
+    static async create(threadId = "cli-session") {
         const rootDir = process.cwd();
         // Configuración de directorios
-        const agentDir = path.join(rootDir, '.agent');
+        const agentDir = path.join(rootDir, ".agent");
         if (!fs.existsSync(agentDir))
             fs.mkdirSync(agentDir, { recursive: true });
         // 1. Persistencia (Checkpointer)
-        const dbPath = path.join(agentDir, 'history.db');
+        const dbPath = path.join(agentDir, "history.db");
         const checkpointer = langgraph_checkpoint_sqlite_1.SqliteSaver.fromConnString(dbPath);
         // 2. Store (Opcional en createAgent, pero lo mantenemos por si lo usas en el runtime)
         const memoryStore = new langgraph_checkpoint_1.InMemoryStore();
@@ -85,7 +85,7 @@ Typing: Strict TypeScript. The use of any is FORBIDDEN.
 
 ⚙️ EXECUTION PROTOCOL:
 
-
+- You operate on a NestJS project. The root directory is: ${process.cwd()}
 RESEARCH (ask_codebase): BEFORE touching anything, search for existing patterns in the project.
 
 Example: "Search for UserEntity before creating a related DTO."
@@ -113,13 +113,14 @@ NOTE ON INDEXING:
       - If 'ask_codebase' fails to find recent changes, use 'refresh_project_index'.
 
 Wait for human approval. If rejected, propose a different solution.
-FILE SYSTEM CONFIGURATION:
-- Real project files are located under: /project/
-- Long-term memories are located under: /memories/
-- The root (/) is for transient scratchpad files only.
+- Use RELATIVE PATHS for all file operations. 
+- All source code is inside the 'src' folder (e.g., 'src/app.module.ts').
+- DO NOT use the '/project/' prefix anymore. Just use the path relative to the root.
+
+🔍 EXAMPLE:
+- Correct: safe_write_file('src/calculator/calculator.controller.ts', '...')
+- Incorrect: safe_write_file('/project/src/...', '...')
 
-ALWAYS use the '/project/' prefix when reading or writing source code.
-Example: write_file('/project/src/app.service.ts', '...')
 🔍 CODE REFINEMENT & INTEGRITY (THE SURGEON'S RULE):
 
 1. Read-Before-Write: NEVER overwrite a file without reading it first using 'safe_read_file'. You must understand the existing logic, TSDocs, and dependencies before making any changes.

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

@@ -1,4 +1,12 @@
 import { z } from 'zod';
+/**
+ * Tool for safely writing content to a file on the real disk.
+ * It creates a backup before writing and then triggers a project re-indexing.
+ * @param {object} params - The parameters for the tool.
+ * @param {string} params.filePath - The relative path where the file should be saved.
+ * @param {string} params.content - The content to write to the file.
+ * @returns {Promise<string>} A message indicating success or failure.
+ */
 export declare const safeWriteFileTool: import("@langchain/core/tools").DynamicStructuredTool<z.ZodObject<{
     filePath: z.ZodString;
     content: z.ZodString;
@@ -9,6 +17,12 @@ export declare const safeWriteFileTool: import("@langchain/core/tools").DynamicS
     filePath: string;
     content: string;
 }, string, "safe_write_file">;
+/**
+ * Tool for safely reading the content of a file from the real disk.
+ * @param {object} params - The parameters for the tool.
+ * @param {string} params.filePath - The relative path of the file to read.
+ * @returns {Promise<string>} The content of the file, or an error message if reading fails.
+ */
 export declare const safeReadFileTool: import("@langchain/core/tools").DynamicStructuredTool<z.ZodObject<{
     filePath: z.ZodString;
 }, z.core.$strip>, {
@@ -17,8 +31,11 @@ export declare const safeReadFileTool: import("@langchain/core/tools").DynamicSt
     filePath: string;
 }, string, "safe_read_file">;
 /**
- * 🔍 TOOL: Ask Codebase (Semantic & Graph Search)
- * This is the Agent's "Eyes". It retrieves code + context.
+ * Tool to query the codebase using semantic search and dependency graph analysis.
+ * It's the primary way for the agent to explore and understand the project structure and logic.
+ * @param {object} params - The parameters for the tool.
+ * @param {string} params.query - A natural language query describing the code or functionality to find.
+ * @returns {Promise<string>} A report containing relevant code snippets, file paths, and dependencies.
  */
 export declare const askCodebaseTool: import("@langchain/core/tools").DynamicStructuredTool<z.ZodObject<{
     query: z.ZodString;
@@ -28,15 +45,15 @@ export declare const askCodebaseTool: import("@langchain/core/tools").DynamicStr
     query: string;
 }, string, "ask_codebase">;
 /**
- * ✅ TOOL: Integrity Check (Compiler)
- * Validates the project state using TypeScript compiler.
+ * Tool to run the TypeScript compiler (tsc) for type checking.
+ * This is crucial for maintaining code quality and catching errors early.
+ * @returns {Promise<string>} A message indicating whether the integrity check passed or failed, including compiler output on failure.
  */
 export declare const integrityCheckTool: import("@langchain/core/tools").DynamicStructuredTool<z.ZodObject<{}, z.core.$strip>, Record<string, never>, Record<string, never>, string, "run_integrity_check">;
 /**
- * Maintenance tool to update the vector knowledge base.
- * * This tool forces a re-read and vectorization of the project files.
- * It is useful for ensuring the LLM has access to the most recent code changes
- * that may not have been synchronized automatically.
- * * @returns {Promise<string>} A confirmation message or error details.
+ * Tool to refresh the project's index, forcing a re-scan and re-vectorization of all files.
+ * This is useful when the agent needs to be absolutely sure it's working with the latest code,
+ * especially after significant changes or if the automatic indexing seems to be lagging.
+ * @returns {Promise<string>} A confirmation message or details about any errors encountered during indexing.
  */
 export declare const refreshIndexTool: import("@langchain/core/tools").DynamicStructuredTool<z.ZodObject<{}, z.core.$strip>, Record<string, never>, Record<string, never>, string, "refresh_project_index">;

package/dist/core/tools/tools.js

@@ -52,41 +52,79 @@ const log = {
     tool: (msg) => console.log(chalk_1.default.yellow('🛠️  [TOOL]: ') + msg),
     sys: (msg) => console.log(chalk_1.default.gray('⚙️  [SYS]: ') + msg),
     error: (msg) => console.log(chalk_1.default.red('❌ [ERR]: ') + msg),
+    debug: (msg) => console.log(chalk_1.default.magenta('🐛 [DEBUG]: ') + msg), // Added for debugging
 };
 /**
- * 💾 Genera un backup antes de modificar un archivo real.
+ * Creates a backup of a file before it is modified.
+ * The backup is stored in the .agent/backups directory with a timestamp.
+ * @param {string} filePath - The relative path of the file to back up.
  */
 const createBackup = (filePath) => {
+    log.debug(`Starting backup process for file: ${filePath}`);
     const rootDir = process.cwd();
     const backupDir = path.join(rootDir, '.agent', 'backups');
-    if (!fs.existsSync(backupDir))
+    log.debug(`Backup directory resolved to: ${backupDir}`);
+    if (!fs.existsSync(backupDir)) {
+        log.debug(`Backup directory does not exist. Creating: ${backupDir}`);
         fs.mkdirSync(backupDir, { recursive: true });
+    }
     const realPath = path.resolve(rootDir, filePath);
+    log.debug(`Resolved real path for backup: ${realPath}`);
     if (fs.existsSync(realPath)) {
         const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
         const filename = path.basename(realPath);
         const backupPath = path.join(backupDir, `${timestamp}_${filename}.bak`);
+        log.debug(`Attempting to copy ${realPath} to ${backupPath}`);
         fs.copyFileSync(realPath, backupPath);
+        log.sys(`Backup created for ${filePath} at ${backupPath}`);
+    }
+    else {
+        log.debug(`File does not exist, no backup needed: ${realPath}`);
     }
 };
+/**
+ * Tool for safely writing content to a file on the real disk.
+ * It creates a backup before writing and then triggers a project re-indexing.
+ * @param {object} params - The parameters for the tool.
+ * @param {string} params.filePath - The relative path where the file should be saved.
+ * @param {string} params.content - The content to write to the file.
+ * @returns {Promise<string>} A message indicating success or failure.
+ */
 exports.safeWriteFileTool = (0, tools_1.tool)(async ({ filePath, content }) => {
+    log.debug(`safe_write_file called with filePath: ${filePath}`);
     try {
         const rootDir = process.cwd();
+        log.debug(`Current working directory: ${rootDir}`);
         const targetPath = path.resolve(rootDir, filePath);
-        if (!targetPath.startsWith(rootDir))
-            return '❌ Error: Access denied.';
+        log.debug(`Resolved target path: ${targetPath}`);
+        // Security check: Ensure the path is within the project root
+        if (!targetPath.startsWith(rootDir)) {
+            log.error(`Attempted write outside root directory: ${filePath}. Resolved path: ${targetPath}`);
+            return '❌ Error: Access denied. Cannot write outside the project root.';
+        }
         const dir = path.dirname(targetPath);
-        if (!fs.existsSync(dir))
+        log.debug(`Directory for target path: ${dir}`);
+        if (!fs.existsSync(dir)) {
+            log.debug(`Directory does not exist. Creating: ${dir}`);
             fs.mkdirSync(dir, { recursive: true });
-        createBackup(filePath); // Tu lógica de backup
+            log.sys(`Created directory: ${dir}`);
+        }
+        createBackup(filePath); // Create backup before writing
+        log.debug(`Writing content to file: ${targetPath}`);
         fs.writeFileSync(targetPath, content, 'utf-8');
-        log.sys(`Indexando cambio en: ${filePath}`);
+        log.sys(`File saved to REAL DISK: ${filePath}`);
+        // Trigger re-indexing after a successful write
+        log.sys(`Initiating re-index for: ${filePath}`);
         const indexer = new indexer_1.IndexerService();
-        indexer.indexProject().catch((err) => log.error(` ${err.message}`));
+        // Run indexing asynchronously, log errors but don't block the write confirmation
+        indexer.indexProject().catch((err) => {
+            log.error(`Failed to re-index after write for ${filePath}: ${err.message}`);
+        });
         return `✅ File saved to REAL DISK: ${filePath}`;
     }
     catch (error) {
-        return `❌ Error: ${error.message}`;
+        log.error(`Failed to write file ${filePath}: ${error.message}`);
+        return `❌ Error writing file: ${error.message}`;
     }
 }, {
     name: 'safe_write_file',
@@ -96,17 +134,36 @@ exports.safeWriteFileTool = (0, tools_1.tool)(async ({ filePath, content }) => {
         content: zod_1.z.string().describe('Full file content'),
     }),
 });
-// --- TOOL 2: READ FILE (Manual) ---
+/**
+ * Tool for safely reading the content of a file from the real disk.
+ * @param {object} params - The parameters for the tool.
+ * @param {string} params.filePath - The relative path of the file to read.
+ * @returns {Promise<string>} The content of the file, or an error message if reading fails.
+ */
 exports.safeReadFileTool = (0, tools_1.tool)(async ({ filePath }) => {
+    log.debug(`safe_read_file called with filePath: ${filePath}`);
     try {
         const rootDir = process.cwd();
+        log.debug(`Current working directory: ${rootDir}`);
         const targetPath = path.resolve(rootDir, filePath);
-        if (!fs.existsSync(targetPath))
-            return '❌ File not found.';
-        return fs.readFileSync(targetPath, 'utf-8');
+        log.debug(`Resolved target path: ${targetPath}`);
+        // Security check: Ensure the path is within the project root
+        if (!fs.existsSync(targetPath)) {
+            log.error(`File not found for reading: ${filePath}. Resolved path: ${targetPath}`);
+            return `❌ File not found: ${filePath}`;
+        }
+        if (!targetPath.startsWith(rootDir)) {
+            log.error(`Attempted read outside root directory: ${filePath}. Resolved path: ${targetPath}`);
+            return '❌ Error: Access denied. Cannot read outside the project root.';
+        }
+        log.debug(`Reading file content from: ${targetPath}`);
+        const content = fs.readFileSync(targetPath, 'utf-8');
+        log.sys(`File read successfully: ${filePath}`);
+        return content;
     }
     catch (e) {
-        return `Error: ${e.message}`;
+        log.error(`Failed to read file ${filePath}: ${e.message}`);
+        return `❌ Error reading file: ${e.message}`;
     }
 }, {
     name: 'safe_read_file',
@@ -114,18 +171,27 @@ exports.safeReadFileTool = (0, tools_1.tool)(async ({ filePath }) => {
     schema: zod_1.z.object({ filePath: zod_1.z.string() }),
 });
 /**
- * 🔍 TOOL: Ask Codebase (Semantic & Graph Search)
- * This is the Agent's "Eyes". It retrieves code + context.
+ * Tool to query the codebase using semantic search and dependency graph analysis.
+ * It's the primary way for the agent to explore and understand the project structure and logic.
+ * @param {object} params - The parameters for the tool.
+ * @param {string} params.query - A natural language query describing the code or functionality to find.
+ * @returns {Promise<string>} A report containing relevant code snippets, file paths, and dependencies.
  */
 exports.askCodebaseTool = (0, tools_1.tool)(async ({ query }) => {
+    log.debug(`ask_codebase called with query: "${query}"`);
     try {
-        // We assume the streaming UI handles the 'Thinking...' log via the framework events
+        log.tool(`Querying codebase: "${query}"`);
         const retriever = new retriever_1.RetrieverService();
+        log.debug('RetrieverService instantiated.');
         const context = await retriever.getContextForLLM(query);
+        log.tool(`Codebase query complete for: "${query}"`);
+        log.debug(`Context retrieved for query "${query}".`);
         return context;
     }
     catch (error) {
-        return `❌ Error querying codebase: ${error}`;
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        log.error(`Error during codebase query "${query}": ${errorMessage}`);
+        return `❌ Error querying codebase: ${errorMessage}`;
     }
 }, {
     name: 'ask_codebase',
@@ -141,20 +207,32 @@ exports.askCodebaseTool = (0, tools_1.tool)(async ({ query }) => {
     }),
 });
 /**
- * ✅ TOOL: Integrity Check (Compiler)
- * Validates the project state using TypeScript compiler.
+ * Tool to run the TypeScript compiler (tsc) for type checking.
+ * This is crucial for maintaining code quality and catching errors early.
+ * @returns {Promise<string>} A message indicating whether the integrity check passed or failed, including compiler output on failure.
  */
 exports.integrityCheckTool = (0, tools_1.tool)(async () => {
+    const rootDir = process.cwd();
+    log.tool('Running TypeScript integrity check...');
+    log.debug(`Integrity check running in directory: ${rootDir}`);
     try {
-        const rootDir = process.cwd();
-        // 'tsc --noEmit' checks types without generating JS files. Fast and safe.
-        const { stdout } = await execAsync('npx tsc --noEmit', { cwd: rootDir });
-        console.log('INTEGRITY CHECK PASSED.', rootDir, stdout);
+        // 'tsc --noEmit' checks types without generating JS files. It's fast and safe.
+        log.debug('Executing command: npx tsc --noEmit');
+        const { stdout, stderr } = await execAsync('npx tsc --noEmit', { cwd: rootDir });
+        if (stderr) {
+            // Log stderr as an error even if stdout indicates success, as tsc might output warnings here
+            log.error(`TypeScript integrity check produced stderr output:\n${stderr}`);
+        }
+        log.tool('TypeScript integrity check PASSED.');
+        log.debug(`Integrity check stdout:\n${stdout}`);
+        // Include stdout in the success message for completeness, though it's usually empty on success.
         return `✅ INTEGRITY CHECK PASSED. The codebase is strictly typed and compiles correctly.\n${stdout}`;
     }
     catch (error) {
-        // 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}`;
+        // Return the exact compiler error output so the agent can attempt to fix it
+        const errorMessage = error.stdout || error.stderr || error.message || 'Unknown error';
+        log.error(`TypeScript integrity check FAILED.\n${errorMessage}`);
+        return `❌ INTEGRITY CHECK FAILED. You must fix these TypeScript errors before finishing:\n${errorMessage}`;
     }
 }, {
     name: 'run_integrity_check',
@@ -163,30 +241,31 @@ exports.integrityCheckTool = (0, tools_1.tool)(async () => {
     schema: zod_1.z.object({}),
 });
 /**
- * Maintenance tool to update the vector knowledge base.
- * * This tool forces a re-read and vectorization of the project files.
- * It is useful for ensuring the LLM has access to the most recent code changes
- * that may not have been synchronized automatically.
- * * @returns {Promise<string>} A confirmation message or error details.
+ * Tool to refresh the project's index, forcing a re-scan and re-vectorization of all files.
+ * This is useful when the agent needs to be absolutely sure it's working with the latest code,
+ * especially after significant changes or if the automatic indexing seems to be lagging.
+ * @returns {Promise<string>} A confirmation message or details about any errors encountered during indexing.
  */
 exports.refreshIndexTool = (0, tools_1.tool)(async () => {
     log.sys('🔄 Starting full project re-indexing...');
     try {
-        // Start the expensive operation
         const indexer = new indexer_1.IndexerService();
-        indexer.indexProject().catch((err) => log.error(` ${err.message}`));
+        log.debug('IndexerService instantiated.');
+        // Execute the indexing process.
+        await indexer.indexProject(); // Await the completion of the indexing process
         log.sys('✅ Re-indexing completed successfully.');
+        log.debug('Project re-indexing process finished.');
         return '✅ Index successfully updated. I now have access to the latest code version.';
     }
     catch (error) {
-        // Safe error handling in TypeScript
+        // Provide a detailed error message if indexing fails.
         const errorMessage = error instanceof Error ? error.message : String(error);
         log.error(`❌ Indexing failed: ${errorMessage}`);
+        log.debug(`Error details during indexing: ${errorMessage}`);
         return `❌ Critical error while attempting to index the project: ${errorMessage}. Please try again or check the logs.`;
     }
 }, {
     name: 'refresh_project_index',
-    // CRITICAL IMPROVEMENT: Instruction-oriented description for the LLM
     description: 'Triggers a forced, full re-indexing of the project codebase. That fucntion is optimazed only index changes comparing hash' +
         'USE THIS TOOL ONLY WHEN: ' +
         '1) The user explicitly states that files have changed. ' +

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dastbal/nestjs-ai-agent",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "Autonomous AI Agent for NestJS - Principal Software Engineer Level with RAG and SQLite persistence",
   "author": "David Balladares",
   "license": "MIT",