@dexto/tools-filesystem 1.5.8 → 1.6.1

package/dist/filesystem-service.cjs

@@ -41,16 +41,19 @@ var import_errors = require("./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;
   initialized = false;
   initPromise = null;
   logger;
+  directoryApprovalChecker;
   /**
    * Create a new FileSystemService with validated configuration.
    *
-   * @param config - Fully-validated configuration from provider schema.
+   * @param config - Fully-validated configuration from the factory schema.
    *                 All required fields have values, defaults already applied.
    * @param logger - Logger instance for this service
    */
@@ -124,8 +127,24 @@ class FileSystemService {
    * @param checker Function that returns true if path is in an approved directory
    */
   setDirectoryApprovalChecker(checker) {
+    this.directoryApprovalChecker = checker;
     this.pathValidator.setDirectoryApprovalChecker(checker);
   }
+  /**
+   * Update the working directory at runtime (e.g., when workspace changes).
+   * Rebuilds the PathValidator so allowed/blocked path roots are recalculated.
+   */
+  setWorkingDirectory(workingDirectory) {
+    const normalized = workingDirectory?.trim();
+    if (!normalized) return;
+    if (this.config.workingDirectory === normalized) return;
+    this.config = { ...this.config, workingDirectory: normalized };
+    this.pathValidator = new import_path_validator.PathValidator(this.config, this.logger);
+    if (this.directoryApprovalChecker) {
+      this.pathValidator.setDirectoryApprovalChecker(this.directoryApprovalChecker);
+    }
+    this.logger.info(`FileSystemService working directory set to ${normalized}`);
+  }
   /**
    * Check if a file path is within the configured allowed paths (config only).
    * This is used by file tools to determine if directory approval is needed.
@@ -136,16 +155,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 import_errors.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()) {
@@ -159,12 +176,18 @@ class FileSystemService {
         );
       }
     } catch (error) {
+      if (error instanceof import_core.DextoRuntimeError && error.scope === "filesystem") {
+        throw error;
+      }
       if (error.code === "ENOENT") {
         throw import_errors.FileSystemError.fileNotFound(normalizedPath);
       }
       if (error.code === "EACCES") {
         throw import_errors.FileSystemError.permissionDenied(normalizedPath, "read");
       }
+      if (error instanceof import_core.DextoRuntimeError) {
+        throw error;
+      }
       throw import_errors.FileSystemError.readFailed(
         normalizedPath,
         error instanceof Error ? error.message : String(error)
@@ -186,20 +209,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 import_core.DextoRuntimeError && error.scope === "filesystem") {
+        throw error;
+      }
       throw import_errors.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
    */
@@ -262,6 +309,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 import_errors.FileSystemError.invalidPath(dirPath, validation.error || "Unknown error");
+    }
+    const normalizedPath = validation.normalizedPath;
+    try {
+      const stats = await fs.stat(normalizedPath);
+      if (!stats.isDirectory()) {
+        throw import_errors.FileSystemError.invalidPath(normalizedPath, "Path is not a directory");
+      }
+    } catch (error) {
+      if (error instanceof import_core.DextoRuntimeError && error.scope === "filesystem") {
+        throw error;
+      }
+      if (error.code === "ENOENT") {
+        throw import_errors.FileSystemError.directoryNotFound(normalizedPath);
+      }
+      if (error.code === "EACCES") {
+        throw import_errors.FileSystemError.permissionDenied(normalizedPath, "read");
+      }
+      throw import_errors.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 import_errors.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 import_errors.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 import_errors.FileSystemError.permissionDenied(normalizedPath, "create directory");
+      }
+      throw import_errors.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 import_errors.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 import_errors.FileSystemError.fileNotFound(normalizedPath);
+      }
+      if (code === "EACCES" || code === "EPERM") {
+        throw import_errors.FileSystemError.permissionDenied(normalizedPath, "delete");
+      }
+      throw import_errors.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 import_errors.FileSystemError.invalidPath(fromPath, fromValidation.error || "Unknown error");
+    }
+    const toValidation = await this.pathValidator.validatePath(toPath);
+    if (!toValidation.isValid || !toValidation.normalizedPath) {
+      throw import_errors.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 import_errors.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 import_errors.FileSystemError.permissionDenied(normalizedTo, "rename");
+      } else {
+        throw import_errors.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 import_errors.FileSystemError.fileNotFound(normalizedFrom);
+      }
+      if (code === "EACCES" || code === "EPERM") {
+        throw import_errors.FileSystemError.permissionDenied(normalizedFrom, "rename");
+      }
+      throw import_errors.FileSystemError.renameFailed(
+        normalizedFrom,
+        error instanceof Error ? error.message : String(error)
+      );
+    }
+  }
   /**
    * Search for content in files (grep-like functionality)
    */

package/dist/filesystem-service.d.ts

@@ -1,36 +1,34 @@
-import { IDextoLogger } from '@dexto/core';
-import { FileSystemConfig, ReadFileOptions, FileContent, GlobOptions, GlobResult, GrepOptions, SearchResult, WriteFileOptions, WriteResult, EditOperation, EditFileOptions, EditResult } from './types.js';
-
 /**
  * FileSystem Service
  *
  * Secure file system operations for Dexto internal tools
  */
-
+import { Logger } from '@dexto/core';
+import { FileSystemConfig, FileContent, ReadFileOptions, GlobOptions, GlobResult, GrepOptions, SearchResult, WriteFileOptions, WriteResult, EditFileOptions, EditResult, EditOperation, ListDirectoryOptions, ListDirectoryResult, CreateDirectoryOptions, CreateDirectoryResult, DeletePathOptions, DeletePathResult, RenamePathResult } from './types.js';
 /**
  * FileSystemService - Handles all file system operations with security checks
  *
- * This service receives fully-validated configuration from the FileSystem Tools Provider.
- * All defaults have been applied by the provider's schema, so the service trusts the config
+ * This service receives fully-validated configuration from the FileSystem Tools Factory.
+ * All defaults have been applied by the factory's schema, so the service trusts the config
  * and uses it as-is without any fallback logic.
  *
- * TODO: Add tests for this class
  * TODO: instantiate only when internal file tools are enabled to avoid file dependencies which won't work in serverless
  */
-declare class FileSystemService {
+export declare class FileSystemService {
     private config;
     private pathValidator;
     private initialized;
     private initPromise;
     private logger;
+    private directoryApprovalChecker?;
     /**
      * Create a new FileSystemService with validated configuration.
      *
-     * @param config - Fully-validated configuration from provider schema.
+     * @param config - Fully-validated configuration from the factory schema.
      *                 All required fields have values, defaults already applied.
      * @param logger - Logger instance for this service
      */
-    constructor(config: FileSystemConfig, logger: IDextoLogger);
+    constructor(config: FileSystemConfig, logger: Logger);
     /**
      * Get backup directory path (context-aware with optional override)
      * TODO: Migrate to explicit configuration via CLI enrichment layer (per-agent paths)
@@ -63,6 +61,11 @@ declare class FileSystemService {
      * @param checker Function that returns true if path is in an approved directory
      */
     setDirectoryApprovalChecker(checker: (filePath: string) => boolean): void;
+    /**
+     * Update the working directory at runtime (e.g., when workspace changes).
+     * Rebuilds the PathValidator so allowed/blocked path roots are recalculated.
+     */
+    setWorkingDirectory(workingDirectory: string): void;
     /**
      * Check if a file path is within the configured allowed paths (config only).
      * This is used by file tools to determine if directory approval is needed.
@@ -71,14 +74,41 @@ declare class FileSystemService {
      * @returns true if the path is within config-allowed paths, false otherwise
      */
     isPathWithinConfigAllowed(filePath: string): Promise<boolean>;
+    private validateReadPath;
+    private readNormalizedFile;
     /**
      * Read a file with validation and size limits
      */
     readFile(filePath: string, options?: ReadFileOptions): Promise<FileContent>;
+    /**
+     * 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.
+     */
+    readFileForToolPreview(filePath: string, options?: ReadFileOptions): Promise<FileContent>;
     /**
      * Find files matching a glob pattern
      */
     globFiles(pattern: string, options?: GlobOptions): Promise<GlobResult>;
+    /**
+     * List contents of a directory (non-recursive)
+     */
+    listDirectory(dirPath: string, options?: ListDirectoryOptions): Promise<ListDirectoryResult>;
+    private mapWithConcurrency;
+    /**
+     * Create a directory
+     */
+    createDirectory(dirPath: string, options?: CreateDirectoryOptions): Promise<CreateDirectoryResult>;
+    /**
+     * Delete a file or directory
+     */
+    deletePath(targetPath: string, options?: DeletePathOptions): Promise<DeletePathResult>;
+    /**
+     * Rename or move a file or directory
+     */
+    renamePath(fromPath: string, toPath: string): Promise<RenamePathResult>;
     /**
      * Search for content in files (grep-like functionality)
      */
@@ -108,5 +138,4 @@ declare class FileSystemService {
      */
     isPathAllowed(filePath: string): Promise<boolean>;
 }
-
-export { FileSystemService };
+//# sourceMappingURL=filesystem-service.d.ts.map

package/dist/filesystem-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filesystem-service.d.ts","sourceRoot":"","sources":["../src/filesystem-service.ts"],"names":[],"mappings":"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"}