topchester-ai 0.3.0 → 0.4.0

package/README.md

@@ -1,5 +1,7 @@
 # Topchester Agent
 
+Website: https://topchester.com
+
 ## Overview
 
 Topchester Agent is a terminal-native TUI coding agent tightly coupled to a committed project knowledge base. The normal workflow is to compile project knowledge first, then let the agent use that knowledge while planning, editing, checking drift, and updating the repository.

package/dist/cli.mjs

@@ -2641,7 +2641,7 @@ const editFileTool = defineTool({
 	execute: (context, args) => editWorkspaceFile(context.workspaceRoot, args, { logger: context.logger })
 });
 async function editWorkspaceFile(workspaceRoot, args, options = {}) {
-	const scopedPath = resolveWorkspaceScopedPath$2(workspaceRoot, args.path);
+	const scopedPath = resolveWorkspaceScopedPath$3(workspaceRoot, args.path);
 	return enqueueFileMutation(scopedPath.path, async () => {
 		const fileStat = await statExistingFile(scopedPath.path, args.path);
 		const beforeBytes = await readFile(scopedPath.path);
@@ -2704,7 +2704,7 @@ function applyExactEdits(content, edits, path = "file") {
 		firstChangedLine: getFirstChangedLine(document.body, newBody)
 	};
 }
-function resolveWorkspaceScopedPath$2(workspaceRoot, path) {
+function resolveWorkspaceScopedPath$3(workspaceRoot, path) {
 	if (path.includes("\0")) throw new Error("edit_file path is invalid.");
 	const resolvedWorkspace = resolve(workspaceRoot);
 	const resolvedPath = isAbsolute(path) ? resolve(path) : resolve(resolvedWorkspace, path);
@@ -2908,7 +2908,7 @@ const findFileTool = defineTool({
 	})
 });
 async function findWorkspaceFilesByName(workspaceRoot, args, options = {}) {
-	const scopedPath = resolveWorkspaceScopedPath$1(workspaceRoot, args.path);
+	const scopedPath = resolveWorkspaceScopedPath$2(workspaceRoot, args.path);
 	const matches = (await collectWorkspaceFiles(scopedPath.workspaceRoot, scopedPath.path, scopedPath.relativePath, options)).map((path) => {
 		const score = scoreFileMatch(args.query, path);
 		return score > 0 ? {
@@ -3106,7 +3106,7 @@ function scoreSubsequenceMatch(query, value) {
 function normalize(value) {
 	return value.trim().toLowerCase().replaceAll("\\", "/");
 }
-function resolveWorkspaceScopedPath$1(workspaceRoot, path) {
+function resolveWorkspaceScopedPath$2(workspaceRoot, path) {
 	const resolvedWorkspace = resolve(workspaceRoot);
 	const resolvedPath = isAbsolute(path) ? resolve(path) : resolve(resolvedWorkspace, path);
 	const relativePath = relative(resolvedWorkspace, resolvedPath);
@@ -3164,7 +3164,7 @@ const grepTool = defineTool({
 	})
 });
 async function grepWorkspace(workspaceRoot, args, options = {}) {
-	const scopedPath = resolveWorkspaceScopedPath(workspaceRoot, args.path ?? ".");
+	const scopedPath = resolveWorkspaceScopedPath$1(workspaceRoot, args.path ?? ".");
 	const executable = await findSearchExecutable(options.pathEnv);
 	if (!executable) {
 		const warning = "grep could not run because neither rg nor grep is available on PATH.";
@@ -3228,7 +3228,7 @@ async function grepWorkspace(workspaceRoot, args, options = {}) {
 		content: truncateToolOutput(result.stdout.trimEnd() || "No matches.")
 	};
 }
-function resolveWorkspaceScopedPath(workspaceRoot, path) {
+function resolveWorkspaceScopedPath$1(workspaceRoot, path) {
 	const resolvedWorkspace = resolve(workspaceRoot);
 	const resolvedPath = isAbsolute(path) ? resolve(path) : resolve(resolvedWorkspace, path);
 	const relativePath = relative(resolvedWorkspace, resolvedPath);
@@ -3286,6 +3286,93 @@ function truncateToolOutput(output) {
 function isRecord$1(value) {
 	return typeof value === "object" && value !== null;
 }
+const listFilesTool = defineTool({
+	name: "list_files",
+	description: "List files and directories inside a workspace folder.",
+	prompt: "list_files: list files and directories inside the workspace; top-level by default, recursive only when requested, with \"/\" after directory names. To use it, reply with only JSON: {\"tool\":\"list_files\",\"args\":{\"path\":\"src\",\"recursive\":false,\"limit\":500}}",
+	argsSchema: z.object({
+		path: z.string().optional().default("."),
+		recursive: z.boolean().optional().default(false),
+		limit: z.number().int().min(1).max(2e3).optional().default(500)
+	}),
+	execute: (context, args) => listWorkspaceFiles(context.workspaceRoot, args)
+});
+async function listWorkspaceFiles(workspaceRoot, args) {
+	const scopedPath = resolveWorkspaceScopedPath(workspaceRoot, args.path);
+	if (!(await stat(scopedPath.path)).isDirectory()) throw new Error(`list_files can only list directories inside the workspace: ${args.path}`);
+	const entries = args.recursive ? await collectRecursiveEntries(scopedPath.workspaceRoot, scopedPath.path, args.limit) : await collectTopLevelEntries(scopedPath.workspaceRoot, scopedPath.path, args.limit);
+	const truncated = entries.truncated;
+	const lines = entries.items.map((entry) => formatEntryPath(entry.relativePath, entry.isDirectory));
+	const notices = [];
+	if (truncated) notices.push(`[${args.limit} entry limit reached. Use a narrower path or a higher limit for more.]`);
+	return {
+		tool: "list_files",
+		path: scopedPath.relativePath,
+		content: [...lines.length > 0 ? lines : ["(empty directory)"], ...notices].join("\n"),
+		warning: truncated ? `${args.limit} entry limit reached.` : void 0
+	};
+}
+async function collectTopLevelEntries(workspaceRoot, startPath, limit) {
+	const entries = await sortedDirectoryEntries(startPath);
+	const items = [];
+	for (const entry of entries) {
+		if (items.length >= limit) return {
+			items,
+			truncated: true
+		};
+		const absolutePath = join(startPath, entry.name);
+		items.push({
+			relativePath: relative(workspaceRoot, absolutePath) || ".",
+			isDirectory: entry.isDirectory()
+		});
+	}
+	return {
+		items,
+		truncated: false
+	};
+}
+async function collectRecursiveEntries(workspaceRoot, startPath, limit) {
+	const items = [];
+	const pending = [startPath];
+	while (pending.length > 0) {
+		const currentPath = pending.shift() ?? startPath;
+		const entries = await sortedDirectoryEntries(currentPath);
+		for (const entry of entries) {
+			if (items.length >= limit) return {
+				items,
+				truncated: true
+			};
+			const absolutePath = join(currentPath, entry.name);
+			const item = {
+				relativePath: relative(workspaceRoot, absolutePath) || ".",
+				isDirectory: entry.isDirectory()
+			};
+			items.push(item);
+			if (item.isDirectory) pending.push(absolutePath);
+		}
+	}
+	return {
+		items,
+		truncated: false
+	};
+}
+async function sortedDirectoryEntries(path) {
+	return (await readdir(path, { withFileTypes: true })).sort((left, right) => left.name.toLowerCase().localeCompare(right.name.toLowerCase()));
+}
+function formatEntryPath(path, isDirectory) {
+	return isDirectory ? `${path}/` : path;
+}
+function resolveWorkspaceScopedPath(workspaceRoot, path) {
+	const resolvedWorkspace = resolve(workspaceRoot);
+	const resolvedPath = isAbsolute(path) ? resolve(path) : resolve(resolvedWorkspace, path);
+	const relativePath = relative(resolvedWorkspace, resolvedPath);
+	if (relativePath.startsWith("..") || isAbsolute(relativePath)) throw new Error(`list_files can only list directories inside the workspace: ${path}`);
+	return {
+		workspaceRoot: resolvedWorkspace,
+		path: resolvedPath,
+		relativePath: relativePath || "."
+	};
+}
 const readFileTool = defineTool({
 	name: "read_file",
 	description: "Read a UTF-8 file inside the workspace.",
@@ -3311,6 +3398,7 @@ async function readWorkspaceFile(workspaceRoot, path) {
 //#region src/agent/tools/registry.ts
 const toolRegistry = {
 	[readFileTool.name]: readFileTool,
+	[listFilesTool.name]: listFilesTool,
 	[grepTool.name]: grepTool,
 	[findFileTool.name]: findFileTool,
 	[editFileTool.name]: editFileTool
@@ -3617,6 +3705,7 @@ function formatToolResultForPrompt(result) {
 function formatToolCallMessage(call, result) {
 	switch (call.tool) {
 		case "read_file": return `Tool read_file: ${call.args.path}`;
+		case "list_files": return `Tool list_files: ${call.args.path}${call.args.recursive ? " (recursive)" : ""}`;
 		case "grep": return `Tool grep: ${call.args.pattern} in ${call.args.path ?? "."}`;
 		case "find_file": return `Tool find_file: ${call.args.query} in ${call.args.path}`;
 		case "edit_file": return `Tool edit_file: ${call.args.path}${formatEditFileChangeSummary(result)}`;