@clinebot/core 0.0.0

package/src/default-tools/executors/editor.ts

@@ -0,0 +1,231 @@
+/**
+ * Editor Executor
+ *
+ * Built-in implementation for filesystem editing operations.
+ */
+
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import type { ToolContext } from "@clinebot/agents";
+import type { EditFileInput } from "../schemas.js";
+import type { EditorExecutor } from "../types.js";
+
+/**
+ * Options for the editor executor
+ */
+export interface EditorExecutorOptions {
+	/**
+	 * File encoding used for read/write operations
+	 * @default "utf-8"
+	 */
+	encoding?: BufferEncoding;
+
+	/**
+	 * Restrict relative-path file operations to paths inside cwd.
+	 * Absolute paths are always accepted as-is.
+	 * @default true
+	 */
+	restrictToCwd?: boolean;
+
+	/**
+	 * Maximum number of diff lines in str_replace output
+	 * @default 200
+	 */
+	maxDiffLines?: number;
+}
+
+function resolveFilePath(
+	cwd: string,
+	inputPath: string,
+	restrictToCwd: boolean,
+): string {
+	const isAbsoluteInput = path.isAbsolute(inputPath);
+	const resolved = isAbsoluteInput
+		? path.normalize(inputPath)
+		: path.resolve(cwd, inputPath);
+	if (!restrictToCwd) {
+		return resolved;
+	}
+
+	// Absolute paths are accepted directly; cwd restriction applies to relative inputs.
+	if (isAbsoluteInput) {
+		return resolved;
+	}
+
+	const rel = path.relative(cwd, resolved);
+	if (rel.startsWith("..") || path.isAbsolute(rel)) {
+		throw new Error(`Path must stay within cwd: ${inputPath}`);
+	}
+	return resolved;
+}
+
+function countOccurrences(content: string, needle: string): number {
+	if (needle.length === 0) return 0;
+	return content.split(needle).length - 1;
+}
+
+function createLineDiff(
+	oldContent: string,
+	newContent: string,
+	maxLines: number,
+): string {
+	const oldLines = oldContent.split("\n");
+	const newLines = newContent.split("\n");
+	const max = Math.max(oldLines.length, newLines.length);
+	const out: string[] = ["```diff"];
+	let emitted = 0;
+
+	for (let i = 0; i < max; i++) {
+		if (emitted >= maxLines) {
+			out.push("... diff truncated ...");
+			break;
+		}
+
+		const oldLine = oldLines[i];
+		const newLine = newLines[i];
+
+		if (oldLine === newLine) {
+			continue;
+		}
+
+		const lineNo = i + 1;
+		if (oldLine !== undefined) {
+			out.push(`-${lineNo}: ${oldLine}`);
+			emitted++;
+		}
+		if (newLine !== undefined && emitted < maxLines) {
+			out.push(`+${lineNo}: ${newLine}`);
+			emitted++;
+		}
+	}
+
+	out.push("```");
+	return out.join("\n");
+}
+
+async function createFile(
+	filePath: string,
+	fileText: string,
+	encoding: BufferEncoding,
+): Promise<string> {
+	await fs.mkdir(path.dirname(filePath), { recursive: true });
+	await fs.writeFile(filePath, fileText, { encoding });
+	return `File created successfully at: ${filePath}`;
+}
+
+async function replaceInFile(
+	filePath: string,
+	oldStr: string,
+	newStr: string | undefined,
+	encoding: BufferEncoding,
+	maxDiffLines: number,
+): Promise<string> {
+	const content = await fs.readFile(filePath, encoding);
+	const occurrences = countOccurrences(content, oldStr);
+
+	if (occurrences === 0) {
+		throw new Error(`No replacement performed: text not found in ${filePath}.`);
+	}
+
+	if (occurrences > 1) {
+		throw new Error(
+			`No replacement performed: multiple occurrences of text found in ${filePath}.`,
+		);
+	}
+
+	const updated = content.replace(oldStr, newStr ?? "");
+	await fs.writeFile(filePath, updated, { encoding });
+
+	const diff = createLineDiff(content, updated, maxDiffLines);
+	return `Edited ${filePath}\n${diff}`;
+}
+
+async function insertInFile(
+	filePath: string,
+	insertLine: number,
+	newStr: string,
+	encoding: BufferEncoding,
+): Promise<string> {
+	const content = await fs.readFile(filePath, encoding);
+	const lines = content.split("\n");
+
+	if (insertLine < 0 || insertLine > lines.length) {
+		throw new Error(
+			`Invalid line number: ${insertLine}. Valid range: 0-${lines.length}`,
+		);
+	}
+
+	lines.splice(insertLine, 0, ...newStr.split("\n"));
+	await fs.writeFile(filePath, lines.join("\n"), { encoding });
+
+	return `Inserted content at line ${insertLine} in ${filePath}.`;
+}
+
+/**
+ * Create an editor executor using Node.js fs module
+ */
+export function createEditorExecutor(
+	options: EditorExecutorOptions = {},
+): EditorExecutor {
+	const {
+		encoding = "utf-8",
+		restrictToCwd = true,
+		maxDiffLines = 200,
+	} = options;
+
+	return async (
+		input: EditFileInput,
+		cwd: string,
+		_context: ToolContext,
+	): Promise<string> => {
+		const filePath = resolveFilePath(cwd, input.path, restrictToCwd);
+
+		switch (input.command) {
+			case "create":
+				if (input.file_text === undefined) {
+					throw new Error(
+						"Parameter `file_text` is required for command: create",
+					);
+				}
+				return createFile(filePath, input.file_text, encoding);
+
+			case "str_replace":
+				if (input.old_str === undefined) {
+					throw new Error(
+						"Parameter `old_str` is required for command: str_replace",
+					);
+				}
+				return replaceInFile(
+					filePath,
+					input.old_str,
+					input.new_str,
+					encoding,
+					maxDiffLines,
+				);
+
+			case "insert":
+				if (input.insert_line === undefined) {
+					throw new Error(
+						"Parameter `insert_line` is required for insert command.",
+					);
+				}
+				if (input.new_str === undefined) {
+					throw new Error(
+						"Parameter `new_str` is required for insert command.",
+					);
+				}
+				return insertInFile(
+					filePath,
+					input.insert_line,
+					input.new_str,
+					encoding,
+				);
+
+			default:
+				throw new Error(
+					`Unrecognized command ${(input as { command: string }).command}. ` +
+						"Allowed commands are: create, str_replace, insert",
+				);
+		}
+	};
+}

package/src/default-tools/executors/file-read.test.ts

@@ -0,0 +1,25 @@
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+import { describe, expect, it } from "vitest";
+import { createFileReadExecutor } from "./file-read.js";
+
+describe("createFileReadExecutor", () => {
+	it("reads a file from an absolute path", async () => {
+		const dir = await fs.mkdtemp(path.join(os.tmpdir(), "agents-file-read-"));
+		const filePath = path.join(dir, "example.txt");
+		await fs.writeFile(filePath, "hello absolute path", "utf-8");
+
+		try {
+			const readFile = createFileReadExecutor();
+			const result = await readFile(filePath, {
+				agentId: "agent-1",
+				conversationId: "conv-1",
+				iteration: 1,
+			});
+			expect(result).toBe("hello absolute path");
+		} finally {
+			await fs.rm(dir, { recursive: true, force: true });
+		}
+	});
+});

package/src/default-tools/executors/file-read.ts

@@ -0,0 +1,94 @@
+/**
+ * File Read Executor
+ *
+ * Built-in implementation for reading files using Node.js fs module.
+ */
+
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import type { ToolContext } from "@clinebot/agents";
+import type { FileReadExecutor } from "../types.js";
+
+/**
+ * Options for the file read executor
+ */
+export interface FileReadExecutorOptions {
+	/**
+	 * Maximum file size to read in bytes
+	 * @default 10_000_000 (10MB)
+	 */
+	maxFileSizeBytes?: number;
+
+	/**
+	 * File encoding
+	 * @default "utf-8"
+	 */
+	encoding?: BufferEncoding;
+
+	/**
+	 * Whether to include line numbers in output
+	 * @default false
+	 */
+	includeLineNumbers?: boolean;
+}
+
+/**
+ * Create a file read executor using Node.js fs module
+ *
+ * @example
+ * ```typescript
+ * const readFile = createFileReadExecutor({
+ *   maxFileSizeBytes: 5_000_000, // 5MB limit
+ *   includeLineNumbers: true,
+ * })
+ *
+ * const content = await readFile("/path/to/file.ts", context)
+ * ```
+ */
+export function createFileReadExecutor(
+	options: FileReadExecutorOptions = {},
+): FileReadExecutor {
+	const {
+		maxFileSizeBytes = 10_000_000,
+		encoding = "utf-8",
+		includeLineNumbers = false,
+	} = options;
+
+	return async (filePath: string, _context: ToolContext): Promise<string> => {
+		const resolvedPath = path.isAbsolute(filePath)
+			? path.normalize(filePath)
+			: path.resolve(process.cwd(), filePath);
+
+		// Check if file exists
+		const stat = await fs.stat(resolvedPath);
+
+		if (!stat.isFile()) {
+			throw new Error(`Path is not a file: ${resolvedPath}`);
+		}
+
+		// Check file size
+		if (stat.size > maxFileSizeBytes) {
+			throw new Error(
+				`File too large: ${stat.size} bytes (max: ${maxFileSizeBytes} bytes). ` +
+					`Consider reading specific sections or using a different approach.`,
+			);
+		}
+
+		// Read file content
+		const content = await fs.readFile(resolvedPath, encoding);
+
+		// Optionally add line numbers
+		if (includeLineNumbers) {
+			const lines = content.split("\n");
+			const maxLineNumWidth = String(lines.length).length;
+			return lines
+				.map(
+					(line, i) =>
+						`${String(i + 1).padStart(maxLineNumWidth, " ")} | ${line}`,
+				)
+				.join("\n");
+		}
+
+		return content;
+	};
+}

package/src/default-tools/executors/index.ts

@@ -0,0 +1,75 @@
+/**
+ * Built-in Executor Implementations
+ *
+ * This module provides ready-to-use implementations of the tool executors
+ * using Node.js built-in modules. These can be used directly or as references
+ * for custom implementations.
+ */
+
+import type { ToolExecutors } from "../types.js";
+import { createApplyPatchExecutor } from "./apply-patch.js";
+import { createBashExecutor } from "./bash.js";
+import { createEditorExecutor } from "./editor.js";
+import { createFileReadExecutor } from "./file-read.js";
+import { createSearchExecutor } from "./search.js";
+import { createWebFetchExecutor } from "./web-fetch.js";
+
+// Re-export individual executors and their options types
+export {
+	type ApplyPatchExecutorOptions,
+	createApplyPatchExecutor,
+} from "./apply-patch.js";
+export { type BashExecutorOptions, createBashExecutor } from "./bash.js";
+export { createEditorExecutor, type EditorExecutorOptions } from "./editor.js";
+export {
+	createFileReadExecutor,
+	type FileReadExecutorOptions,
+} from "./file-read.js";
+export { createSearchExecutor, type SearchExecutorOptions } from "./search.js";
+export {
+	createWebFetchExecutor,
+	type WebFetchExecutorOptions,
+} from "./web-fetch.js";
+
+/**
+ * Options for creating default executors
+ */
+export interface DefaultExecutorsOptions {
+	fileRead?: import("./file-read.js").FileReadExecutorOptions;
+	search?: import("./search.js").SearchExecutorOptions;
+	bash?: import("./bash.js").BashExecutorOptions;
+	webFetch?: import("./web-fetch.js").WebFetchExecutorOptions;
+	applyPatch?: import("./apply-patch.js").ApplyPatchExecutorOptions;
+	editor?: import("./editor.js").EditorExecutorOptions;
+}
+
+/**
+ * Create all default executors with optional configuration
+ *
+ * @example
+ * ```typescript
+ * import { createDefaultTools, createDefaultExecutors } from "@clinebot/core/server"
+ *
+ * const executors = createDefaultExecutors({
+ *   bash: { timeoutMs: 60000 },
+ *   search: { maxResults: 50 },
+ * })
+ *
+ * const tools = createDefaultTools({
+ *   executors,
+ *   cwd: "/path/to/project",
+ * })
+ * ```
+ */
+export function createDefaultExecutors(
+	options: DefaultExecutorsOptions = {},
+): ToolExecutors {
+	return {
+		readFile: createFileReadExecutor(options.fileRead),
+		search: createSearchExecutor(options.search),
+		bash: createBashExecutor(options.bash),
+		webFetch: createWebFetchExecutor(options.webFetch),
+		applyPatch: createApplyPatchExecutor(options.applyPatch),
+		editor: createEditorExecutor(options.editor),
+	};
+}

package/src/default-tools/executors/search.ts

@@ -0,0 +1,278 @@
+/**
+ * Search Executor
+ *
+ * Built-in implementation for searching the codebase using regex.
+ */
+
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import type { ToolContext } from "@clinebot/agents";
+import { getFileIndex } from "../../input";
+import type { SearchExecutor } from "../types.js";
+
+/**
+ * Options for the search executor
+ */
+export interface SearchExecutorOptions {
+	/**
+	 * File extensions to include in search (without dot)
+	 * @default common code extensions
+	 */
+	includeExtensions?: string[];
+
+	/**
+	 * Directories to exclude from search
+	 * @default ["node_modules", ".git", "dist", "build", ".next", "coverage"]
+	 */
+	excludeDirs?: string[];
+
+	/**
+	 * Maximum number of results to return
+	 * @default 100
+	 */
+	maxResults?: number;
+
+	/**
+	 * Number of context lines before and after match
+	 * @default 2
+	 */
+	contextLines?: number;
+
+	/**
+	 * Maximum depth to traverse
+	 * @default 20
+	 */
+	maxDepth?: number;
+}
+
+const DEFAULT_INCLUDE_EXTENSIONS = [
+	"ts",
+	"tsx",
+	"js",
+	"jsx",
+	"mjs",
+	"cjs",
+	"json",
+	"md",
+	"mdx",
+	"txt",
+	"yaml",
+	"yml",
+	"toml",
+	"py",
+	"rb",
+	"go",
+	"rs",
+	"java",
+	"kt",
+	"swift",
+	"c",
+	"cpp",
+	"h",
+	"hpp",
+	"css",
+	"scss",
+	"less",
+	"html",
+	"vue",
+	"svelte",
+	"sql",
+	"sh",
+	"bash",
+	"zsh",
+	"fish",
+	"ps1",
+	"env",
+	"gitignore",
+	"dockerignore",
+	"editorconfig",
+];
+
+const DEFAULT_EXCLUDE_DIRS = [
+	"node_modules",
+	".git",
+	"dist",
+	"build",
+	".next",
+	"coverage",
+	"__pycache__",
+	".venv",
+	"venv",
+	".cache",
+	".turbo",
+	".output",
+	"out",
+	"target",
+	"bin",
+	"obj",
+];
+
+/**
+ * Search result for a single file match
+ */
+interface SearchMatch {
+	file: string;
+	line: number;
+	column: number;
+	match: string;
+	context: string[];
+}
+
+function shouldIncludeFile(
+	relativePath: string,
+	excludeDirs: Set<string>,
+	includeExtensions: Set<string>,
+	maxDepth: number,
+): boolean {
+	const segments = relativePath.split("/");
+	const fileName = segments[segments.length - 1] ?? "";
+	const directoryDepth = segments.length - 1;
+
+	if (directoryDepth > maxDepth) {
+		return false;
+	}
+
+	for (let i = 0; i < segments.length - 1; i++) {
+		if (excludeDirs.has(segments[i] ?? "")) {
+			return false;
+		}
+	}
+
+	const ext = path.posix.extname(fileName).slice(1).toLowerCase();
+	return includeExtensions.has(ext) || (!ext && !fileName.startsWith("."));
+}
+
+/**
+ * Create a search executor using regex pattern matching
+ *
+ * @example
+ * ```typescript
+ * const search = createSearchExecutor({
+ *   maxResults: 50,
+ *   contextLines: 3,
+ * })
+ *
+ * const results = await search("function\\s+handleClick", "/path/to/project", context)
+ * ```
+ */
+export function createSearchExecutor(
+	options: SearchExecutorOptions = {},
+): SearchExecutor {
+	const {
+		includeExtensions = DEFAULT_INCLUDE_EXTENSIONS,
+		excludeDirs = DEFAULT_EXCLUDE_DIRS,
+		maxResults = 100,
+		contextLines = 2,
+		maxDepth = 20,
+	} = options;
+	const excludeDirsSet = new Set(excludeDirs);
+	const includeExtensionsSet = new Set(
+		includeExtensions.map((extension) => extension.toLowerCase()),
+	);
+
+	return async (
+		query: string,
+		cwd: string,
+		_context: ToolContext,
+	): Promise<string> => {
+		// Compile regex
+		let regex: RegExp;
+		try {
+			regex = new RegExp(query, "gim");
+		} catch (error) {
+			throw new Error(
+				`Invalid regex pattern: ${query}. ${error instanceof Error ? error.message : ""}`,
+			);
+		}
+
+		const matches: SearchMatch[] = [];
+		let totalFilesSearched = 0;
+
+		const fileList = await getFileIndex(cwd);
+
+		// Search files from the fast index.
+		for (const relativePath of fileList) {
+			if (
+				!shouldIncludeFile(
+					relativePath,
+					excludeDirsSet,
+					includeExtensionsSet,
+					maxDepth,
+				)
+			) {
+				continue;
+			}
+
+			if (matches.length >= maxResults) break;
+
+			totalFilesSearched++;
+			const filePath = path.join(cwd, relativePath);
+
+			try {
+				const content = await fs.readFile(filePath, "utf-8");
+				const lines = content.split("\n");
+
+				for (let lineIdx = 0; lineIdx < lines.length; lineIdx++) {
+					const line = lines[lineIdx];
+					regex.lastIndex = 0; // Reset regex state
+
+					let match: RegExpExecArray | null;
+					while ((match = regex.exec(line)) !== null) {
+						if (matches.length >= maxResults) break;
+
+						// Get context lines
+						const contextStart = Math.max(0, lineIdx - contextLines);
+						const contextEnd = Math.min(
+							lines.length - 1,
+							lineIdx + contextLines,
+						);
+						const contextLinesArr: string[] = [];
+
+						for (let i = contextStart; i <= contextEnd; i++) {
+							const prefix = i === lineIdx ? ">" : " ";
+							contextLinesArr.push(`${prefix} ${i + 1}: ${lines[i]}`);
+						}
+
+						matches.push({
+							file: relativePath,
+							line: lineIdx + 1,
+							column: match.index + 1,
+							match: match[0],
+							context: contextLinesArr,
+						});
+
+						// Prevent infinite loop on zero-length matches
+						if (match.index === regex.lastIndex) {
+							regex.lastIndex++;
+						}
+					}
+				}
+			} catch {}
+		}
+
+		// Format results
+		if (matches.length === 0) {
+			return `No results found for pattern: ${query}\nSearched ${totalFilesSearched} files.`;
+		}
+
+		const resultLines: string[] = [
+			`Found ${matches.length} result${matches.length === 1 ? "" : "s"} for pattern: ${query}`,
+			`Searched ${totalFilesSearched} files.`,
+			"",
+		];
+
+		for (const match of matches) {
+			resultLines.push(`${match.file}:${match.line}:${match.column}`);
+			resultLines.push(...match.context);
+			resultLines.push("");
+		}
+
+		if (matches.length >= maxResults) {
+			resultLines.push(
+				`(Showing first ${maxResults} results. Refine your search for more specific results.)`,
+			);
+		}
+
+		return resultLines.join("\n");
+	};
+}