@dexto/tools-filesystem 1.6.0 → 1.6.2

package/dist/filesystem-service.js

@@ -2,12 +2,14 @@ import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import { glob } from "glob";
 import safeRegex from "safe-regex";
-import { getDextoPath, DextoLogComponent } from "@dexto/core";
+import { DextoRuntimeError, getDextoPath, DextoLogComponent } from "@dexto/core";
 import { PathValidator } from "./path-validator.js";
 import { FileSystemError } from "./errors.js";
 const DEFAULT_ENCODING = "utf-8";
 const DEFAULT_MAX_RESULTS = 1e3;
 const DEFAULT_MAX_SEARCH_RESULTS = 100;
+const DEFAULT_MAX_LIST_RESULTS = 5e3;
+const DEFAULT_LIST_CONCURRENCY = 16;
 class FileSystemService {
   config;
   pathValidator;
@@ -120,16 +122,14 @@ class FileSystemService {
   async isPathWithinConfigAllowed(filePath) {
     return this.pathValidator.isPathWithinAllowed(filePath);
   }
-  /**
-   * Read a file with validation and size limits
-   */
-  async readFile(filePath, options = {}) {
-    await this.ensureInitialized();
-    const validation = await this.pathValidator.validatePath(filePath);
+  async validateReadPath(filePath, mode) {
+    const validation = mode === "toolPreview" ? await this.pathValidator.validatePathForPreview(filePath) : await this.pathValidator.validatePath(filePath);
     if (!validation.isValid || !validation.normalizedPath) {
       throw FileSystemError.invalidPath(filePath, validation.error || "Unknown error");
     }
-    const normalizedPath = validation.normalizedPath;
+    return validation.normalizedPath;
+  }
+  async readNormalizedFile(normalizedPath, options = {}) {
     try {
       const stats = await fs.stat(normalizedPath);
       if (!stats.isFile()) {
@@ -143,12 +143,18 @@ class FileSystemService {
         );
       }
     } catch (error) {
+      if (error instanceof DextoRuntimeError && error.scope === "filesystem") {
+        throw error;
+      }
       if (error.code === "ENOENT") {
         throw FileSystemError.fileNotFound(normalizedPath);
       }
       if (error.code === "EACCES") {
         throw FileSystemError.permissionDenied(normalizedPath, "read");
       }
+      if (error instanceof DextoRuntimeError) {
+        throw error;
+      }
       throw FileSystemError.readFailed(
         normalizedPath,
         error instanceof Error ? error.message : String(error)
@@ -170,20 +176,44 @@ class FileSystemService {
       } else {
         selectedLines = lines;
       }
+      const returnedContent = selectedLines.join("\n");
       return {
-        content: selectedLines.join("\n"),
+        content: returnedContent,
         lines: selectedLines.length,
         encoding,
         truncated,
-        size: Buffer.byteLength(content, encoding)
+        size: Buffer.byteLength(returnedContent, encoding)
       };
     } catch (error) {
+      if (error instanceof DextoRuntimeError && error.scope === "filesystem") {
+        throw error;
+      }
       throw FileSystemError.readFailed(
         normalizedPath,
         error instanceof Error ? error.message : String(error)
       );
     }
   }
+  /**
+   * Read a file with validation and size limits
+   */
+  async readFile(filePath, options = {}) {
+    await this.ensureInitialized();
+    const normalizedPath = await this.validateReadPath(filePath, "execute");
+    return await this.readNormalizedFile(normalizedPath, options);
+  }
+  /**
+   * Preview-only file read that bypasses config-allowed roots.
+   *
+   * This is intended for UI previews (diffs, create previews) shown BEFORE a user
+   * confirms directory access for the tool call. The returned content is UI-only
+   * and should not be forwarded to the LLM.
+   */
+  async readFileForToolPreview(filePath, options = {}) {
+    await this.ensureInitialized();
+    const normalizedPath = await this.validateReadPath(filePath, "toolPreview");
+    return await this.readNormalizedFile(normalizedPath, options);
+  }
   /**
    * Find files matching a glob pattern
    */
@@ -246,6 +276,274 @@ class FileSystemService {
       );
     }
   }
+  /**
+   * List contents of a directory (non-recursive)
+   */
+  async listDirectory(dirPath, options = {}) {
+    await this.ensureInitialized();
+    const validation = await this.pathValidator.validatePath(dirPath);
+    if (!validation.isValid || !validation.normalizedPath) {
+      throw FileSystemError.invalidPath(dirPath, validation.error || "Unknown error");
+    }
+    const normalizedPath = validation.normalizedPath;
+    try {
+      const stats = await fs.stat(normalizedPath);
+      if (!stats.isDirectory()) {
+        throw FileSystemError.invalidPath(normalizedPath, "Path is not a directory");
+      }
+    } catch (error) {
+      if (error instanceof DextoRuntimeError && error.scope === "filesystem") {
+        throw error;
+      }
+      if (error.code === "ENOENT") {
+        throw FileSystemError.directoryNotFound(normalizedPath);
+      }
+      if (error.code === "EACCES") {
+        throw FileSystemError.permissionDenied(normalizedPath, "read");
+      }
+      throw FileSystemError.listFailed(
+        normalizedPath,
+        error instanceof Error ? error.message : String(error)
+      );
+    }
+    const includeHidden = options.includeHidden ?? true;
+    const includeMetadata = options.includeMetadata !== false;
+    const maxEntries = options.maxEntries ?? DEFAULT_MAX_LIST_RESULTS;
+    try {
+      const dirEntries = await fs.readdir(normalizedPath, { withFileTypes: true });
+      const candidates = dirEntries.filter(
+        (entry) => includeHidden || !entry.name.startsWith(".")
+      );
+      const concurrency = DEFAULT_LIST_CONCURRENCY;
+      const validatedEntries = await this.mapWithConcurrency(
+        candidates,
+        concurrency,
+        async (entry) => {
+          const entryPath = path.join(normalizedPath, entry.name);
+          const entryValidation = await this.pathValidator.validatePath(entryPath);
+          if (!entryValidation.isValid || !entryValidation.normalizedPath) {
+            return null;
+          }
+          return {
+            entry,
+            normalizedPath: entryValidation.normalizedPath
+          };
+        }
+      );
+      const validEntries = validatedEntries.filter(Boolean);
+      if (maxEntries <= 0) {
+        return {
+          path: normalizedPath,
+          entries: [],
+          truncated: validEntries.length > 0,
+          totalEntries: validEntries.length
+        };
+      }
+      if (!includeMetadata) {
+        const entries2 = validEntries.slice(0, maxEntries).map((entry) => ({
+          name: entry.entry.name,
+          path: entry.normalizedPath,
+          isDirectory: entry.entry.isDirectory(),
+          size: 0,
+          modified: /* @__PURE__ */ new Date()
+        }));
+        return {
+          path: normalizedPath,
+          entries: entries2,
+          truncated: validEntries.length > maxEntries,
+          totalEntries: validEntries.length
+        };
+      }
+      const metadataEntries = await this.mapWithConcurrency(
+        validEntries,
+        concurrency,
+        async (entry) => {
+          try {
+            const stat = await fs.stat(entry.normalizedPath);
+            return {
+              name: entry.entry.name,
+              path: entry.normalizedPath,
+              isDirectory: entry.entry.isDirectory(),
+              size: stat.size,
+              modified: stat.mtime
+            };
+          } catch {
+            return null;
+          }
+        }
+      );
+      const entries = [];
+      let successfulStats = 0;
+      let cutoffIndex = -1;
+      for (let index = 0; index < metadataEntries.length; index += 1) {
+        const entry = metadataEntries[index];
+        if (!entry) {
+          continue;
+        }
+        successfulStats += 1;
+        if (entries.length < maxEntries) {
+          entries.push(entry);
+        }
+        if (successfulStats === maxEntries) {
+          cutoffIndex = index;
+        }
+      }
+      const remainingSuccessful = cutoffIndex >= 0 ? metadataEntries.slice(cutoffIndex + 1).filter((entry) => entry !== null).length : 0;
+      const totalEntries = successfulStats < maxEntries ? successfulStats : maxEntries + remainingSuccessful;
+      return {
+        path: normalizedPath,
+        entries,
+        truncated: totalEntries > maxEntries,
+        totalEntries
+      };
+    } catch (error) {
+      throw FileSystemError.listFailed(
+        normalizedPath,
+        error instanceof Error ? error.message : String(error)
+      );
+    }
+  }
+  async mapWithConcurrency(items, limit, mapper) {
+    if (items.length === 0) {
+      return [];
+    }
+    const results = new Array(items.length);
+    let nextIndex = 0;
+    const workerCount = Math.min(Math.max(1, limit), items.length);
+    const workers = Array.from({ length: workerCount }, async () => {
+      while (true) {
+        const current = nextIndex++;
+        if (current >= items.length) {
+          return;
+        }
+        const item = items[current];
+        if (item === void 0) {
+          continue;
+        }
+        results[current] = await mapper(item, current);
+      }
+    });
+    await Promise.all(workers);
+    return results;
+  }
+  /**
+   * Create a directory
+   */
+  async createDirectory(dirPath, options = {}) {
+    await this.ensureInitialized();
+    const validation = await this.pathValidator.validatePath(dirPath);
+    if (!validation.isValid || !validation.normalizedPath) {
+      throw FileSystemError.invalidPath(dirPath, validation.error || "Unknown error");
+    }
+    const normalizedPath = validation.normalizedPath;
+    const recursive = options.recursive ?? false;
+    try {
+      const firstCreated = await fs.mkdir(normalizedPath, { recursive });
+      const created = recursive ? typeof firstCreated === "string" : true;
+      return { path: normalizedPath, created };
+    } catch (error) {
+      const code = error.code;
+      if (code === "EEXIST") {
+        try {
+          const stat = await fs.stat(normalizedPath);
+          if (stat.isDirectory()) {
+            return { path: normalizedPath, created: false };
+          }
+        } catch {
+        }
+      }
+      if (code === "EACCES" || code === "EPERM") {
+        throw FileSystemError.permissionDenied(normalizedPath, "create directory");
+      }
+      throw FileSystemError.createDirFailed(
+        normalizedPath,
+        error instanceof Error ? error.message : String(error)
+      );
+    }
+  }
+  /**
+   * Delete a file or directory
+   */
+  async deletePath(targetPath, options = {}) {
+    await this.ensureInitialized();
+    const validation = await this.pathValidator.validatePath(targetPath);
+    if (!validation.isValid || !validation.normalizedPath) {
+      throw FileSystemError.invalidPath(targetPath, validation.error || "Unknown error");
+    }
+    const normalizedPath = validation.normalizedPath;
+    try {
+      await fs.rm(normalizedPath, { recursive: options.recursive ?? false, force: false });
+      return { path: normalizedPath, deleted: true };
+    } catch (error) {
+      const code = error.code;
+      if (code === "ENOENT") {
+        throw FileSystemError.fileNotFound(normalizedPath);
+      }
+      if (code === "EACCES" || code === "EPERM") {
+        throw FileSystemError.permissionDenied(normalizedPath, "delete");
+      }
+      throw FileSystemError.deleteFailed(
+        normalizedPath,
+        error instanceof Error ? error.message : String(error)
+      );
+    }
+  }
+  /**
+   * Rename or move a file or directory
+   */
+  async renamePath(fromPath, toPath) {
+    await this.ensureInitialized();
+    const fromValidation = await this.pathValidator.validatePath(fromPath);
+    if (!fromValidation.isValid || !fromValidation.normalizedPath) {
+      throw FileSystemError.invalidPath(fromPath, fromValidation.error || "Unknown error");
+    }
+    const toValidation = await this.pathValidator.validatePath(toPath);
+    if (!toValidation.isValid || !toValidation.normalizedPath) {
+      throw FileSystemError.invalidPath(toPath, toValidation.error || "Unknown error");
+    }
+    const normalizedFrom = fromValidation.normalizedPath;
+    const normalizedTo = toValidation.normalizedPath;
+    if (normalizedFrom === normalizedTo) {
+      return { from: normalizedFrom, to: normalizedTo };
+    }
+    try {
+      await fs.access(normalizedTo);
+      throw FileSystemError.renameFailed(
+        normalizedFrom,
+        `Target already exists: ${normalizedTo}`
+      );
+    } catch (error) {
+      const code = error.code;
+      if (!code) {
+        throw error;
+      }
+      if (code === "ENOENT") {
+      } else if (code === "EACCES" || code === "EPERM") {
+        throw FileSystemError.permissionDenied(normalizedTo, "rename");
+      } else {
+        throw FileSystemError.renameFailed(
+          normalizedFrom,
+          error instanceof Error ? error.message : String(error)
+        );
+      }
+    }
+    try {
+      await fs.rename(normalizedFrom, normalizedTo);
+      return { from: normalizedFrom, to: normalizedTo };
+    } catch (error) {
+      const code = error.code;
+      if (code === "ENOENT") {
+        throw FileSystemError.fileNotFound(normalizedFrom);
+      }
+      if (code === "EACCES" || code === "EPERM") {
+        throw FileSystemError.permissionDenied(normalizedFrom, "rename");
+      }
+      throw FileSystemError.renameFailed(
+        normalizedFrom,
+        error instanceof Error ? error.message : String(error)
+      );
+    }
+  }
   /**
    * Search for content in files (grep-like functionality)
    */

package/dist/glob-files-tool.cjs

@@ -43,13 +43,24 @@ const GlobFilesInputSchema = import_zod.z.object({
 function createGlobFilesTool(getFileSystemService) {
   return (0, import_core.defineTool)({
     id: "glob_files",
-    displayName: "Find Files",
     aliases: ["glob"],
     description: "Find files matching a glob pattern. Supports standard glob syntax like **/*.js for recursive matches, *.ts for files in current directory, and src/**/*.tsx for nested paths. Returns array of file paths with metadata (size, modified date). Results are limited to allowed paths only.",
     inputSchema: GlobFilesInputSchema,
+    presentation: {
+      describeHeader: (input) => {
+        const bits = [`pattern=${input.pattern}`];
+        if (input.path) bits.push(`path=${input.path}`);
+        if (typeof input.max_results === "number") bits.push(`max=${input.max_results}`);
+        return (0, import_core.createLocalToolCallHeader)({
+          title: "Find Files",
+          argsText: (0, import_core.truncateForHeader)(bits.join(", "), 140)
+        });
+      }
+    },
     ...(0, import_directory_approval.createDirectoryAccessApprovalHandlers)({
       toolName: "glob_files",
       operation: "read",
+      inputSchema: GlobFilesInputSchema,
       getFileSystemService,
       resolvePaths: (input, fileSystemService) => {
         const baseDir = fileSystemService.getWorkingDirectory();

package/dist/glob-files-tool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"glob-files-tool.d.ts","sourceRoot":"","sources":["../src/glob-files-tool.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,KAAK,EAAE,IAAI,EAAwB,MAAM,aAAa,CAAC;AAC9D,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AAGpE,QAAA,MAAM,oBAAoB;;;;;;;;;;;;EAiBb,CAAC;AAEd;;GAEG;AACH,wBAAgB,mBAAmB,CAC/B,oBAAoB,EAAE,uBAAuB,GAC9C,IAAI,CAAC,OAAO,oBAAoB,CAAC,CA8DnC"}
+{"version":3,"file":"glob-files-tool.d.ts","sourceRoot":"","sources":["../src/glob-files-tool.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,KAAK,EAAE,IAAI,EAAwB,MAAM,aAAa,CAAC;AAC9D,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AAGpE,QAAA,MAAM,oBAAoB;;;;;;;;;;;;EAiBb,CAAC;AAEd;;GAEG;AACH,wBAAgB,mBAAmB,CAC/B,oBAAoB,EAAE,uBAAuB,GAC9C,IAAI,CAAC,OAAO,oBAAoB,CAAC,CA2EnC"}

package/dist/glob-files-tool.js

@@ -1,6 +1,6 @@
 import * as path from "node:path";
 import { z } from "zod";
-import { defineTool } from "@dexto/core";
+import { createLocalToolCallHeader, defineTool, truncateForHeader } from "@dexto/core";
 import { createDirectoryAccessApprovalHandlers } from "./directory-approval.js";
 const GlobFilesInputSchema = z.object({
   pattern: z.string().describe('Glob pattern to match files (e.g., "**/*.ts", "src/**/*.js")'),
@@ -10,13 +10,24 @@ const GlobFilesInputSchema = z.object({
 function createGlobFilesTool(getFileSystemService) {
   return defineTool({
     id: "glob_files",
-    displayName: "Find Files",
     aliases: ["glob"],
     description: "Find files matching a glob pattern. Supports standard glob syntax like **/*.js for recursive matches, *.ts for files in current directory, and src/**/*.tsx for nested paths. Returns array of file paths with metadata (size, modified date). Results are limited to allowed paths only.",
     inputSchema: GlobFilesInputSchema,
+    presentation: {
+      describeHeader: (input) => {
+        const bits = [`pattern=${input.pattern}`];
+        if (input.path) bits.push(`path=${input.path}`);
+        if (typeof input.max_results === "number") bits.push(`max=${input.max_results}`);
+        return createLocalToolCallHeader({
+          title: "Find Files",
+          argsText: truncateForHeader(bits.join(", "), 140)
+        });
+      }
+    },
     ...createDirectoryAccessApprovalHandlers({
       toolName: "glob_files",
       operation: "read",
+      inputSchema: GlobFilesInputSchema,
       getFileSystemService,
       resolvePaths: (input, fileSystemService) => {
         const baseDir = fileSystemService.getWorkingDirectory();

package/dist/grep-content-tool.cjs

@@ -48,13 +48,25 @@ const GrepContentInputSchema = import_zod.z.object({
 function createGrepContentTool(getFileSystemService) {
   return (0, import_core.defineTool)({
     id: "grep_content",
-    displayName: "Search Files",
     aliases: ["grep"],
     description: 'Search for text patterns in files using regular expressions. Returns matching lines with file path, line number, and optional context lines. Use glob parameter to filter specific file types (e.g., "*.ts"). Supports case-insensitive search. Great for finding code patterns, function definitions, or specific text across multiple files.',
     inputSchema: GrepContentInputSchema,
+    presentation: {
+      describeHeader: (input) => {
+        const bits = [`pattern=${input.pattern}`];
+        if (input.glob) bits.push(`glob=${input.glob}`);
+        if (input.path) bits.push(`path=${input.path}`);
+        if (typeof input.max_results === "number") bits.push(`max=${input.max_results}`);
+        return (0, import_core.createLocalToolCallHeader)({
+          title: "Search Files",
+          argsText: (0, import_core.truncateForHeader)(bits.join(", "), 140)
+        });
+      }
+    },
     ...(0, import_directory_approval.createDirectoryAccessApprovalHandlers)({
       toolName: "grep_content",
       operation: "read",
+      inputSchema: GrepContentInputSchema,
       getFileSystemService,
       resolvePaths: (input, fileSystemService) => {
         const baseDir = fileSystemService.getWorkingDirectory();

package/dist/grep-content-tool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"grep-content-tool.d.ts","sourceRoot":"","sources":["../src/grep-content-tool.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,KAAK,EAAE,IAAI,EAAwB,MAAM,aAAa,CAAC;AAC9D,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AAGpE,QAAA,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;EAiCf,CAAC;AAEd;;GAEG;AACH,wBAAgB,qBAAqB,CACjC,oBAAoB,EAAE,uBAAuB,GAC9C,IAAI,CAAC,OAAO,sBAAsB,CAAC,CA+ErC"}
+{"version":3,"file":"grep-content-tool.d.ts","sourceRoot":"","sources":["../src/grep-content-tool.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,KAAK,EAAE,IAAI,EAAwB,MAAM,aAAa,CAAC;AAC9D,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AAGpE,QAAA,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;EAiCf,CAAC;AAEd;;GAEG;AACH,wBAAgB,qBAAqB,CACjC,oBAAoB,EAAE,uBAAuB,GAC9C,IAAI,CAAC,OAAO,sBAAsB,CAAC,CA6FrC"}

package/dist/grep-content-tool.js

@@ -1,6 +1,6 @@
 import * as path from "node:path";
 import { z } from "zod";
-import { defineTool } from "@dexto/core";
+import { createLocalToolCallHeader, defineTool, truncateForHeader } from "@dexto/core";
 import { createDirectoryAccessApprovalHandlers } from "./directory-approval.js";
 const GrepContentInputSchema = z.object({
   pattern: z.string().describe("Regular expression pattern to search for"),
@@ -15,13 +15,25 @@ const GrepContentInputSchema = z.object({
 function createGrepContentTool(getFileSystemService) {
   return defineTool({
     id: "grep_content",
-    displayName: "Search Files",
     aliases: ["grep"],
     description: 'Search for text patterns in files using regular expressions. Returns matching lines with file path, line number, and optional context lines. Use glob parameter to filter specific file types (e.g., "*.ts"). Supports case-insensitive search. Great for finding code patterns, function definitions, or specific text across multiple files.',
     inputSchema: GrepContentInputSchema,
+    presentation: {
+      describeHeader: (input) => {
+        const bits = [`pattern=${input.pattern}`];
+        if (input.glob) bits.push(`glob=${input.glob}`);
+        if (input.path) bits.push(`path=${input.path}`);
+        if (typeof input.max_results === "number") bits.push(`max=${input.max_results}`);
+        return createLocalToolCallHeader({
+          title: "Search Files",
+          argsText: truncateForHeader(bits.join(", "), 140)
+        });
+      }
+    },
     ...createDirectoryAccessApprovalHandlers({
       toolName: "grep_content",
       operation: "read",
+      inputSchema: GrepContentInputSchema,
       getFileSystemService,
       resolvePaths: (input, fileSystemService) => {
         const baseDir = fileSystemService.getWorkingDirectory();

package/dist/index.cjs

@@ -21,6 +21,7 @@ __export(index_exports, {
   FileSystemError: () => import_errors.FileSystemError,
   FileSystemErrorCode: () => import_error_codes.FileSystemErrorCode,
   FileSystemService: () => import_filesystem_service.FileSystemService,
+  FileSystemToolsConfigSchema: () => import_tool_factory_config.FileSystemToolsConfigSchema,
   PathValidator: () => import_path_validator.PathValidator,
   createEditFileTool: () => import_edit_file_tool.createEditFileTool,
   createGlobFilesTool: () => import_glob_files_tool.createGlobFilesTool,
@@ -31,6 +32,7 @@ __export(index_exports, {
 });
 module.exports = __toCommonJS(index_exports);
 var import_tool_factory = require("./tool-factory.js");
+var import_tool_factory_config = require("./tool-factory-config.js");
 var import_filesystem_service = require("./filesystem-service.js");
 var import_path_validator = require("./path-validator.js");
 var import_errors = require("./errors.js");
@@ -45,6 +47,7 @@ var import_grep_content_tool = require("./grep-content-tool.js");
   FileSystemError,
   FileSystemErrorCode,
   FileSystemService,
+  FileSystemToolsConfigSchema,
   PathValidator,
   createEditFileTool,
   createGlobFilesTool,