@4onstudios/iris-agent 0.1.0

package/dist/api/core/agent/tools/readFile.js

@@ -0,0 +1,337 @@
+import fs from "fs/promises";
+import path from "path";
+import { execFile } from "child_process";
+import { promisify } from "util";
+import { z } from "zod";
+import { knowledgeGraph } from "../../library/knowledgeGraph.js";
+import { findFilesViaRepoMap, rankFileCandidates, } from "../utils/repoMapIndex.js";
+import { buildRecoveryQueries } from "../utils/pathRecovery.js";
+const execFileAsync = promisify(execFile);
+const MAX_READ_LINES = 500;
+const normalizeRelativeInputPath = (value) => value.replace(/\\/g, "/").replace(/^\.\//, "").replace(/^\//, "");
+const isPathInsideBase = (basePath, targetPath) => {
+    const relative = path.relative(basePath, targetPath);
+    return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+};
+const findFileViaTerminal = async (cwd, query) => {
+    const normalizedQuery = normalizeRelativeInputPath(query);
+    const baseName = path.basename(normalizedQuery);
+    const attempts = [];
+    if (normalizedQuery && normalizedQuery !== baseName) {
+        attempts.push([
+            ".",
+            "-type",
+            "f",
+            "-path",
+            `./${normalizedQuery}`,
+        ]);
+    }
+    if (baseName) {
+        attempts.push([".", "-type", "f", "-name", baseName]);
+    }
+    for (const args of attempts) {
+        try {
+            const { stdout } = await execFileAsync("find", args, {
+                cwd,
+                maxBuffer: 1024 * 1024 * 4,
+            });
+            const firstMatch = stdout
+                .split(/\r?\n/)
+                .map((line) => line.trim())
+                .filter(Boolean);
+            const rankedMatches = await rankFileCandidates(cwd, query, firstMatch.map((match) => path.resolve(cwd, match)));
+            const bestMatch = rankedMatches[0];
+            if (bestMatch) {
+                return bestMatch;
+            }
+        }
+        catch {
+            // Ignore and continue to next fallback strategy.
+        }
+    }
+    return null;
+};
+/**
+ * Detect language from file extension
+ */
+function detectLanguage(filePath) {
+    const ext = path.extname(filePath).toLowerCase().replace(/^\./, "");
+    if (!ext) {
+        return "text";
+    }
+    switch (ext) {
+        case "js":
+            return "javascript";
+        case "jsx":
+            return "jsx";
+        case "ts":
+            return "typescript";
+        case "tsx":
+            return "tsx";
+        case "py":
+            return "python";
+        case "java":
+            return "java";
+        case "go":
+            return "go";
+        case "cpp":
+            return "cpp";
+        case "c":
+            return "c";
+        case "cs":
+            return "csharp";
+        case "rb":
+            return "ruby";
+        case "php":
+            return "php";
+        default:
+            return "text";
+    }
+}
+/**
+ * Tool for reading file contents
+ * @param {Object} params - The parameters for reading a file
+ * @param {string} params.filePath - The path to the file to read
+ * @param {string} [params.encoding='utf8'] - The encoding to use when reading the file
+ * @param {boolean} [params.parseWithKnowledgeGraph=true] - Whether to parse file with knowledge graph
+ * @returns {Promise<Object>} Object containing success status and file content or error
+ */
+export async function readFile({ filePath, workspaceRoot, encoding = "utf8", parseWithKnowledgeGraph = true, startLine, endLine, withLineNumbers, }) {
+    try {
+        // Validate input
+        if (!filePath) {
+            return {
+                success: false,
+                error: "File path is required",
+            };
+        }
+        if ((startLine === undefined) !== (endLine === undefined)) {
+            return {
+                success: false,
+                error: "Both startLine and endLine must be provided together",
+            };
+        }
+        if (startLine !== undefined && endLine !== undefined) {
+            const validatedEndLine = endLine;
+            if (!Number.isInteger(startLine)
+                || !Number.isInteger(validatedEndLine)
+                || startLine < 1
+                || validatedEndLine < 1) {
+                return {
+                    success: false,
+                    error: "startLine and endLine must be positive integers",
+                };
+            }
+        }
+        if (startLine !== undefined
+            && endLine !== undefined
+            && startLine > endLine) {
+            return {
+                success: false,
+                error: "startLine cannot be greater than endLine",
+            };
+        }
+        // Prefer the active workspace root when provided so reads keep working
+        // after the UI switches folders without changing the server cwd.
+        const effectiveWorkspaceRoot = workspaceRoot || process.cwd();
+        const absoluteWorkspaceRoot = path.resolve(effectiveWorkspaceRoot);
+        // If path is already absolute, use it; otherwise resolve from workspace root.
+        // Reads are allowed outside the workspace root when the resolved path is
+        // directly readable, so callers can inspect sibling repos and shared files.
+        const absolutePath = path.isAbsolute(filePath)
+            ? path.resolve(filePath)
+            : path.join(effectiveWorkspaceRoot, filePath);
+        let readablePath = absolutePath;
+        let resolvedBy = "direct";
+        // Check if file exists
+        try {
+            await fs.access(readablePath, fs.constants.R_OK);
+        }
+        catch {
+            const recoveryQueries = buildRecoveryQueries(filePath, absoluteWorkspaceRoot);
+            let recoveredPath = null;
+            let recoveredByRepoMap = false;
+            for (const query of recoveryQueries) {
+                const fromRepoMap = await findFilesViaRepoMap(effectiveWorkspaceRoot, query, 1);
+                const recoveredPathCandidate = fromRepoMap[0] || (await findFileViaTerminal(effectiveWorkspaceRoot, query));
+                const safeRecoveredPath = recoveredPathCandidate
+                    && isPathInsideBase(absoluteWorkspaceRoot, path.resolve(recoveredPathCandidate))
+                    ? recoveredPathCandidate
+                    : null;
+                if (safeRecoveredPath) {
+                    recoveredPath = safeRecoveredPath;
+                    recoveredByRepoMap = Boolean(fromRepoMap[0]);
+                    break;
+                }
+            }
+            if (!recoveredPath) {
+                return {
+                    success: false,
+                    error: `File not found or not readable: ${filePath}`,
+                    attemptedPath: absolutePath,
+                };
+            }
+            readablePath = recoveredPath;
+            resolvedBy = recoveredByRepoMap ? "repo_map" : "terminal_find";
+        }
+        // Get file stats
+        const stats = await fs.stat(readablePath);
+        if (!stats.isFile()) {
+            return {
+                success: false,
+                error: `Path is not a file: ${filePath}`,
+            };
+        }
+        // Read file content
+        const fullContent = await fs.readFile(readablePath, encoding);
+        let content = fullContent;
+        let selectedStartLine;
+        let selectedEndLine;
+        let totalLines;
+        const shouldChunkText = encoding === "utf8" || encoding === "ascii";
+        if (shouldChunkText) {
+            const lines = fullContent.split("\n");
+            totalLines = lines.length;
+            const requestedStartLine = startLine ?? 1;
+            const requestedEndLine = endLine ?? totalLines;
+            if (requestedStartLine > totalLines) {
+                return {
+                    success: false,
+                    error: `Start line ${requestedStartLine} exceeds file length (${totalLines} lines)`,
+                };
+            }
+            selectedStartLine = requestedStartLine;
+            selectedEndLine = Math.min(requestedEndLine, selectedStartLine + MAX_READ_LINES - 1, totalLines);
+            const selectedLines = lines.slice(selectedStartLine - 1, selectedEndLine);
+            const shouldAddLineNumbers = withLineNumbers ?? startLine !== undefined;
+            content = shouldAddLineNumbers
+                ? selectedLines
+                    .map((line, index) => `${selectedStartLine + index}:${line}`)
+                    .join("\n")
+                : selectedLines.join("\n");
+        }
+        // Parse with knowledge graph if enabled and file is code
+        let parseResult = null;
+        const language = detectLanguage(readablePath);
+        const codeLanguages = [
+            "javascript",
+            "jsx",
+            "typescript",
+            "tsx",
+            "python",
+            "java",
+            "go",
+        ];
+        if (parseWithKnowledgeGraph && codeLanguages.includes(language)) {
+            try {
+                knowledgeGraph.indexFile({
+                    path: readablePath,
+                    name: path.basename(readablePath),
+                    content: fullContent,
+                    language,
+                });
+                // Get code summary from knowledge graph
+                const node = knowledgeGraph.nodes.get(readablePath);
+                if (node) {
+                    const parsedComponents = Array.from(knowledgeGraph.nodes.values())
+                        .filter((n) => n.metadata.filePath === readablePath && n.id !== readablePath)
+                        .map((n) => ({
+                        type: n.type,
+                        name: String(n.metadata.name || n.id.split(":").pop() || ""),
+                        line: n.metadata.startLine,
+                    }));
+                    parseResult = {
+                        parsed: true,
+                        language,
+                        components: parsedComponents,
+                        tokenCount: node.tokenCount,
+                        relationships: Array.from(node.relationships).map((rel) => ({
+                            type: rel.type,
+                            target: rel.nodeId,
+                        })),
+                    };
+                }
+            }
+            catch (parseError) {
+                const error = parseError;
+                console.error("Knowledge graph parsing error:", parseError);
+                parseResult = {
+                    parsed: false,
+                    error: error.message,
+                };
+            }
+        }
+        return {
+            success: true,
+            filePath: readablePath,
+            resolvedBy,
+            content,
+            ...(selectedStartLine !== undefined
+                ? {
+                    startLine: selectedStartLine,
+                    endLine: selectedEndLine,
+                    totalLines,
+                    hasMore: selectedEndLine < totalLines,
+                    ...(selectedEndLine < totalLines
+                        ? {
+                            nextStartLine: selectedEndLine + 1,
+                            nextEndLine: Math.min(selectedEndLine + MAX_READ_LINES, totalLines),
+                        }
+                        : {}),
+                }
+                : {}),
+            size: stats.size,
+            lastModified: stats.mtime,
+            knowledgeGraph: parseResult,
+        };
+    }
+    catch (error) {
+        const err = error;
+        return {
+            success: false,
+            error: err.message,
+        };
+    }
+}
+/**
+ * Tool metadata for agent system
+ */
+export const readFileTool = {
+    name: "read_file",
+    description: "Read up to 500 lines of a file. Use startLine and endLine with the returned next range to continue reading large files",
+    parameters: z.object({
+        filePath: z
+            .string()
+            .describe("The path to the file to read (can be relative or absolute)"),
+        workspaceRoot: z
+            .string()
+            .optional()
+            .describe("Workspace root used for path validation and recovery"),
+        encoding: z
+            .enum(["utf8", "ascii", "base64", "binary", "hex"])
+            .default("utf8")
+            .describe("The encoding to use when reading the file"),
+        startLine: z
+            .number()
+            .int()
+            .positive()
+            .optional()
+            .describe("First line to return (1-based, inclusive). Must be provided together with endLine"),
+        endLine: z
+            .number()
+            .int()
+            .positive()
+            .optional()
+            .describe("Last line to return (1-based, inclusive). Must be provided together with startLine"),
+        withLineNumbers: z
+            .boolean()
+            .optional()
+            .describe("Prefix each returned line with its line number. Defaults to true when a range is requested"),
+        parseWithKnowledgeGraph: z
+            .boolean()
+            .default(true)
+            .describe("Whether to automatically parse code files with the knowledge graph for enhanced analysis"),
+    }),
+    execute: readFile,
+};
+export default readFileTool;

package/dist/api/core/agent/tools/renameFile.d.ts

@@ -0,0 +1,49 @@
+import { z } from "zod";
+type RenameFileParams = {
+    oldPath: string;
+    newPath: string;
+    overwrite?: boolean;
+};
+type RenameFileSuccessResult = {
+    success: true;
+    oldPath: string;
+    newPath: string;
+    size: number;
+    isMove: boolean;
+    message: string;
+};
+type RenameFileErrorResult = {
+    success: false;
+    error: string;
+};
+type RenameFileResult = RenameFileSuccessResult | RenameFileErrorResult;
+/**
+ * Tool for renaming or moving files
+ * @param {Object} params - The parameters for renaming a file
+ * @param {string} params.oldPath - The current path of the file
+ * @param {string} params.newPath - The new path for the file
+ * @param {boolean} [params.overwrite=false] - Whether to overwrite if destination exists
+ * @returns {Promise<Object>} Object containing success status and rename info or error
+ */
+export declare function renameFile({ oldPath, newPath, overwrite, }: RenameFileParams): Promise<RenameFileResult>;
+/**
+ * Tool metadata for agent system
+ */
+export declare const renameFileTool: {
+    description: string;
+    parameters: z.ZodObject<{
+        oldPath: z.ZodString;
+        newPath: z.ZodString;
+        overwrite: z.ZodDefault<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        oldPath?: string;
+        newPath?: string;
+        overwrite?: boolean;
+    }, {
+        oldPath?: string;
+        newPath?: string;
+        overwrite?: boolean;
+    }>;
+    execute: typeof renameFile;
+};
+export default renameFileTool;

package/dist/api/core/agent/tools/renameFile.js

@@ -0,0 +1,86 @@
+import fs from "fs/promises";
+import path from "path";
+import { z } from "zod";
+/**
+ * Tool for renaming or moving files
+ * @param {Object} params - The parameters for renaming a file
+ * @param {string} params.oldPath - The current path of the file
+ * @param {string} params.newPath - The new path for the file
+ * @param {boolean} [params.overwrite=false] - Whether to overwrite if destination exists
+ * @returns {Promise<Object>} Object containing success status and rename info or error
+ */
+export async function renameFile({ oldPath, newPath, overwrite = false, }) {
+    try {
+        // Validate input
+        if (!oldPath || !newPath) {
+            return {
+                success: false,
+                error: "Both oldPath and newPath are required",
+            };
+        }
+        // Resolve to absolute paths
+        const absoluteOldPath = path.resolve(oldPath);
+        const absoluteNewPath = path.resolve(newPath);
+        // Check if source file exists
+        try {
+            await fs.access(absoluteOldPath, fs.constants.F_OK);
+        }
+        catch (err) {
+            return {
+                success: false,
+                error: `Source file not found: ${oldPath}`,
+            };
+        }
+        // Check if destination exists
+        try {
+            await fs.access(absoluteNewPath, fs.constants.F_OK);
+            if (!overwrite) {
+                return {
+                    success: false,
+                    error: `Destination already exists: ${newPath}. Set overwrite=true to replace.`,
+                };
+            }
+        }
+        catch (err) {
+            // Destination doesn't exist, which is fine
+        }
+        // Create destination directory if it doesn't exist
+        const destDir = path.dirname(absoluteNewPath);
+        await fs.mkdir(destDir, { recursive: true });
+        // Get file stats before moving
+        const stats = await fs.stat(absoluteOldPath);
+        // Rename/move the file
+        await fs.rename(absoluteOldPath, absoluteNewPath);
+        return {
+            success: true,
+            oldPath: absoluteOldPath,
+            newPath: absoluteNewPath,
+            size: stats.size,
+            isMove: path.dirname(absoluteOldPath) !== path.dirname(absoluteNewPath),
+            message: "File renamed/moved successfully",
+        };
+    }
+    catch (error) {
+        const err = error;
+        return {
+            success: false,
+            error: err.message,
+        };
+    }
+}
+/**
+ * Tool metadata for agent system
+ */
+export const renameFileTool = {
+    description: "Rename or move a file to a new location",
+    parameters: z.object({
+        oldPath: z.string().describe("The current path of the file"),
+        newPath: z.string().describe("The new path for the file"),
+        overwrite: z
+            .boolean()
+            .default(false)
+            .describe("Whether to overwrite if destination exists"),
+    }),
+    execute: renameFile,
+};
+export default renameFileTool;

package/dist/api/core/agent/tools/renameSymbol.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Rename Symbol Tool
+ * Uses LSP to rename a symbol across the whole workspace.
+ */
+type RenameSymbolParams = {
+    filePath: string;
+    line: number;
+    character: number;
+    newName: string;
+};
+type FileChange = {
+    filePath: string;
+    editCount: number;
+    edits: Array<{
+        startLine: number;
+        startCharacter: number;
+        endLine: number;
+        endCharacter: number;
+        newText: string;
+    }>;
+};
+type RenameSymbolResult = {
+    success: true;
+    filePath: string;
+    position: {
+        line: number;
+        character: number;
+    };
+    newName: string;
+    totalFiles: number;
+    totalEdits: number;
+    files: FileChange[];
+} | {
+    success: false;
+    message?: string;
+    error?: string;
+    filePath: string;
+    position: {
+        line: number;
+        character: number;
+    };
+};
+declare const renameSymbolTool: {
+    name: string;
+    description: string;
+    parameters: {
+        type: string;
+        properties: {
+            filePath: {
+                type: string;
+                description: string;
+            };
+            line: {
+                type: string;
+                description: string;
+            };
+            character: {
+                type: string;
+                description: string;
+            };
+            newName: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+    execute({ filePath, line, character, newName }: RenameSymbolParams): Promise<RenameSymbolResult>;
+};
+export default renameSymbolTool;

package/dist/api/core/agent/tools/renameSymbol.js

@@ -0,0 +1,106 @@
+/**
+ * Rename Symbol Tool
+ * Uses LSP to rename a symbol across the whole workspace.
+ */
+import { coreLsp } from "../../library/lsp/coreLsp.js";
+import fs from "fs/promises";
+import { fileURLToPath } from "url";
+const renameSymbolTool = {
+    name: "renameSymbol",
+    description: `Rename a symbol (variable, function, class, etc.) across the entire workspace using LSP.
+Safely renames all references to the symbol at the given position.
+
+Use this when you need to:
+- Rename a function, class, or variable consistently everywhere it is used
+- Refactor code with confidence that all call sites are updated
+- Understand the full scope of a rename before applying it`,
+    parameters: {
+        type: "object",
+        properties: {
+            filePath: {
+                type: "string",
+                description: "Absolute path to the file containing the symbol",
+            },
+            line: {
+                type: "number",
+                description: "Line number (1-based) of the symbol to rename",
+            },
+            character: {
+                type: "number",
+                description: "Character position (1-based) on the line",
+            },
+            newName: {
+                type: "string",
+                description: "The new name for the symbol",
+            },
+        },
+        required: ["filePath", "line", "character", "newName"],
+    },
+    async execute({ filePath, line, character, newName }) {
+        try {
+            await fs.access(filePath);
+            const result = (await coreLsp.renameSymbol(filePath, line, character, newName));
+            if (!result) {
+                return {
+                    success: false,
+                    message: `No rename result for symbol at ${filePath}:${line}:${character}`,
+                    filePath,
+                    position: { line, character },
+                };
+            }
+            const files = [];
+            const processEdits = (uri, edits) => {
+                let filePath;
+                try {
+                    filePath = uri.startsWith("file://") ? fileURLToPath(uri) : uri;
+                }
+                catch {
+                    filePath = uri.replace("file://", "");
+                }
+                files.push({
+                    filePath,
+                    editCount: edits.length,
+                    edits: edits.map((edit) => ({
+                        startLine: (edit.range?.start?.line ?? 0) + 1,
+                        startCharacter: (edit.range?.start?.character ?? 0) + 1,
+                        endLine: (edit.range?.end?.line ?? 0) + 1,
+                        endCharacter: (edit.range?.end?.character ?? 0) + 1,
+                        newText: edit.newText ?? newName,
+                    })),
+                });
+            };
+            if (result.changes) {
+                for (const [uri, edits] of Object.entries(result.changes)) {
+                    processEdits(uri, edits);
+                }
+            }
+            else if (result.documentChanges) {
+                for (const change of result.documentChanges) {
+                    if (change.textDocument?.uri) {
+                        processEdits(change.textDocument.uri, change.edits ?? []);
+                    }
+                }
+            }
+            const totalEdits = files.reduce((sum, f) => sum + f.editCount, 0);
+            return {
+                success: true,
+                filePath,
+                position: { line, character },
+                newName,
+                totalFiles: files.length,
+                totalEdits,
+                files,
+            };
+        }
+        catch (error) {
+            const err = error;
+            return {
+                success: false,
+                error: err.message,
+                filePath,
+                position: { line, character },
+            };
+        }
+    },
+};
+export default renameSymbolTool;