@dastbal/nestjs-ai-agent 1.0.0

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

@@ -0,0 +1,42 @@
+import { z } from 'zod';
+export declare const safeWriteFileTool: import("@langchain/core/tools").DynamicStructuredTool<z.ZodObject<{
+    filePath: z.ZodString;
+    content: z.ZodString;
+}, z.core.$strip>, {
+    filePath: string;
+    content: string;
+}, {
+    filePath: string;
+    content: string;
+}, string, "safe_write_file">;
+export declare const safeReadFileTool: import("@langchain/core/tools").DynamicStructuredTool<z.ZodObject<{
+    filePath: z.ZodString;
+}, z.core.$strip>, {
+    filePath: string;
+}, {
+    filePath: string;
+}, string, "safe_read_file">;
+/**
+ * 🔍 TOOL: Ask Codebase (Semantic & Graph Search)
+ * This is the Agent's "Eyes". It retrieves code + context.
+ */
+export declare const askCodebaseTool: import("@langchain/core/tools").DynamicStructuredTool<z.ZodObject<{
+    query: z.ZodString;
+}, z.core.$strip>, {
+    query: string;
+}, {
+    query: string;
+}, string, "ask_codebase">;
+/**
+ * ✅ TOOL: Integrity Check (Compiler)
+ * Validates the project state using TypeScript compiler.
+ */
+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.
+ */
+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

@@ -0,0 +1,196 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.refreshIndexTool = exports.integrityCheckTool = exports.askCodebaseTool = exports.safeReadFileTool = exports.safeWriteFileTool = void 0;
+const tools_1 = require("@langchain/core/tools");
+const zod_1 = require("zod");
+const child_process_1 = require("child_process");
+const util_1 = require("util");
+const retriever_1 = require("../rag/retriever");
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const chalk_1 = __importDefault(require("chalk"));
+const indexer_1 = require("../rag/indexer");
+const execAsync = (0, util_1.promisify)(child_process_1.exec);
+const log = {
+    ai: (msg) => console.log(chalk_1.default.blue('🤖 [AI]: ') + msg),
+    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),
+};
+/**
+ * 💾 Genera un backup antes de modificar un archivo real.
+ */
+const createBackup = (filePath) => {
+    const rootDir = process.cwd();
+    const backupDir = path.join(rootDir, '.agent', 'backups');
+    if (!fs.existsSync(backupDir))
+        fs.mkdirSync(backupDir, { recursive: true });
+    const realPath = path.resolve(rootDir, filePath);
+    if (fs.existsSync(realPath)) {
+        const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+        const filename = path.basename(realPath);
+        const backupPath = path.join(backupDir, `${timestamp}_${filename}.bak`);
+        fs.copyFileSync(realPath, backupPath);
+    }
+};
+exports.safeWriteFileTool = (0, tools_1.tool)(async ({ filePath, content }) => {
+    try {
+        const rootDir = process.cwd();
+        const targetPath = path.resolve(rootDir, filePath);
+        if (!targetPath.startsWith(rootDir))
+            return '❌ Error: Access denied.';
+        const dir = path.dirname(targetPath);
+        if (!fs.existsSync(dir))
+            fs.mkdirSync(dir, { recursive: true });
+        createBackup(filePath); // Tu lógica de backup
+        fs.writeFileSync(targetPath, content, 'utf-8');
+        log.sys(`Indexando cambio en: ${filePath}`);
+        const indexer = new indexer_1.IndexerService();
+        indexer.indexProject().catch((err) => log.error(` ${err.message}`));
+        return `✅ File saved to REAL DISK: ${filePath}`;
+    }
+    catch (error) {
+        return `❌ Error: ${error.message}`;
+    }
+}, {
+    name: 'safe_write_file',
+    description: 'WRITES code to the REAL local disk. Creates a backup automatically.',
+    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'),
+    }),
+});
+// --- TOOL 2: READ FILE (Manual) ---
+exports.safeReadFileTool = (0, tools_1.tool)(async ({ filePath }) => {
+    try {
+        const rootDir = process.cwd();
+        const targetPath = path.resolve(rootDir, filePath);
+        if (!fs.existsSync(targetPath))
+            return '❌ File not found.';
+        return fs.readFileSync(targetPath, 'utf-8');
+    }
+    catch (e) {
+        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() }),
+});
+/**
+ * 🔍 TOOL: Ask Codebase (Semantic & Graph Search)
+ * This is the Agent's "Eyes". It retrieves code + context.
+ */
+exports.askCodebaseTool = (0, tools_1.tool)(async ({ query }) => {
+    try {
+        // We assume the streaming UI handles the 'Thinking...' log via the framework events
+        const retriever = new retriever_1.RetrieverService();
+        const context = await retriever.getContextForLLM(query);
+        return context;
+    }
+    catch (error) {
+        return `❌ Error querying codebase: ${error}`;
+    }
+}, {
+    name: 'ask_codebase',
+    description: 'CRITICAL TOOL. Use this tool FIRST to explore the codebase. ' +
+        'It performs a semantic search AND a dependency graph lookup. ' +
+        'Returns: Relevant code snippets, lists of dependencies (imports), and ACCURATE FILE PATHS. ' +
+        'Strategy: Use this to find *where* logic is located. If you need the full file content to edit it safely, ' +
+        "copy the 'FILE PATH' returned by this tool and use the native 'read_file' tool.",
+    schema: zod_1.z.object({
+        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')"),
+    }),
+});
+/**
+ * ✅ TOOL: Integrity Check (Compiler)
+ * Validates the project state using TypeScript compiler.
+ */
+exports.integrityCheckTool = (0, tools_1.tool)(async () => {
+    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);
+        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}`;
+    }
+}, {
+    name: 'run_integrity_check',
+    description: 'Runs the TypeScript compiler (tsc) to verify type safety. ' +
+        "MANDATORY: Run this tool after every 'write_file' or 'edit_file' operation to ensure you haven't broken the build.",
+    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.
+ */
+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.sys('✅ Re-indexing completed successfully.');
+        return '✅ Index successfully updated. I now have access to the latest code version.';
+    }
+    catch (error) {
+        // Safe error handling in TypeScript
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        log.error(`❌ Indexing failed: ${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. ' +
+        '2) You cannot find information that should be present (stale context). ' +
+        'Note: This is a computationally expensive operation; inform the user before running it.',
+    schema: zod_1.z.object({}),
+});

package/dist/core/types.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Represents the type of relation between two files in the project.
+ * - 'import': Standard ES6 import.
+ * - 'extends': Class inheritance.
+ * - 'implements': Interface implementation.
+ */
+export type DependencyRelation = 'import' | 'extends' | 'implements' | 'injects';
+/**
+ * Represents the granularity of a code chunk.
+ * - 'file': The whole file (e.g., DTOs, Entities).
+ * - 'method': A specific function inside a class (e.g., Service methods).
+ * - 'class_signature': The class definition line + properties (Parent context).
+ */
+export type ChunkType = 'file' | 'method' | 'class_signature' | 'config';
+/**
+ * Structure of a row in the Dependency Graph table.
+ */
+export interface GraphEdge {
+    sourcePath: string;
+    targetPath: string;
+    relation: DependencyRelation;
+}
+/**
+ * Metadata stored alongside vectors to help the LLM understand context.
+ */
+export interface ChunkMetadata {
+    startLine: number;
+    endLine: number;
+    decorators?: string[];
+    className?: string;
+    methodName?: string;
+}
+/**
+ * Represents a processed piece of code ready for storage.
+ */
+export interface ProcessedChunk {
+    id: string;
+    filePath?: string;
+    type: ChunkType;
+    content: string;
+    metadata: ChunkMetadata;
+    parentId?: string;
+}
+/**
+ * Full analysis result of a single file.
+ */
+export interface FileAnalysisResult {
+    filePath: string;
+    fileHash: string;
+    chunks: ProcessedChunk[];
+    dependencies: GraphEdge[];
+    skeleton: object | null;
+}

package/dist/core/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./ai-agent.module";
+export * from "./core/agent/factory";
+export * from "./core/llm/provider";
+export * from "./core/tools/tools";

package/dist/index.js

@@ -0,0 +1,23 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+// Exportamos el Módulo para NestJS
+__exportStar(require("./ai-agent.module"), exports);
+// Exportamos la Factory y los tipos por si alguien quiere uso manual
+__exportStar(require("./core/agent/factory"), exports);
+__exportStar(require("./core/llm/provider"), exports);
+// Exportamos las herramientas por si el usuario quiere crear su propio agente
+__exportStar(require("./core/tools/tools"), exports);

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@dastbal/nestjs-ai-agent",
+  "version": "1.0.0",
+  "description": "Autonomous AI Agent for NestJS - Principal Software Engineer Level with RAG and SQLite persistence",
+  "author": "David Balladares",
+  "license": "MIT",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "gen": "dist/bin/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc",
+    "gen": "ts-node src/bin/cli.ts",
+    "start:dev": "ts-node src/bin/cli.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@langchain/google-vertexai": "^2.1.6",
+    "@langchain/langgraph": "1.0.7",
+    "@langchain/langgraph-checkpoint-sqlite": "^1.0.0",
+    "better-sqlite3": "^12.5.0",
+    "chalk": "^4.1.2",
+    "commander": "^14.0.2",
+    "deepagents": "^1.6.1",
+    "dotenv": "^17.2.3",
+    "langchain": "^1.2.7",
+    "sqlite3": "^5.1.7",
+    "ts-morph": "^27.0.2",
+    "uuid": "^13.0.0",
+    "zod": "^4.3.5"
+  },
+  "peerDependencies": {
+    "@nestjs/common": "^10.0.0",
+    "reflect-metadata": "^0.1.13"
+  },
+  "devDependencies": {
+    "@nestjs/common": "^10.4.22",
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/node": "^20.19.30",
+    "@types/uuid": "^10.0.0",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.0.0"
+  }
+}