@dexto/tools-filesystem 1.5.8 → 1.6.1

package/dist/filesystem-service.js

@@ -2,22 +2,25 @@ 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;
   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
    */
@@ -91,8 +94,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 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.
@@ -103,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()) {
@@ -126,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)
@@ -153,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
    */
@@ -229,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/filesystem-service.test.cjs

@@ -36,10 +36,12 @@ const createMockLogger = () => ({
 (0, import_vitest.describe)("FileSystemService", () => {
   let mockLogger;
   let tempDir;
+  let backupDir;
   (0, import_vitest.beforeEach)(async () => {
     mockLogger = createMockLogger();
     const rawTempDir = await fs.mkdtemp(path.join(os.tmpdir(), "dexto-fs-test-"));
     tempDir = await fs.realpath(rawTempDir);
+    backupDir = path.join(tempDir, ".dexto", "backups");
     import_vitest.vi.clearAllMocks();
   });
   (0, import_vitest.afterEach)(async () => {
@@ -59,6 +61,7 @@ const createMockLogger = () => ({
             maxFileSize: 10 * 1024 * 1024,
             workingDirectory: tempDir,
             enableBackups: false,
+            backupPath: backupDir,
             backupRetentionDays: 7
           },
           mockLogger
@@ -69,7 +72,6 @@ const createMockLogger = () => ({
         const result = await fileSystemService.writeFile(testFile, "new content");
         (0, import_vitest.expect)(result.success).toBe(true);
         (0, import_vitest.expect)(result.backupPath).toBeUndefined();
-        const backupDir = path.join(tempDir, ".dexto-backups");
         try {
           const files = await fs.readdir(backupDir);
           (0, import_vitest.expect)(files.length).toBe(0);
@@ -85,6 +87,7 @@ const createMockLogger = () => ({
             maxFileSize: 10 * 1024 * 1024,
             workingDirectory: tempDir,
             enableBackups: true,
+            backupPath: backupDir,
             backupRetentionDays: 7
           },
           mockLogger
@@ -95,7 +98,7 @@ const createMockLogger = () => ({
         const result = await fileSystemService.writeFile(testFile, "new content");
         (0, import_vitest.expect)(result.success).toBe(true);
         (0, import_vitest.expect)(result.backupPath).toBeDefined();
-        (0, import_vitest.expect)(result.backupPath).toContain(".dexto");
+        (0, import_vitest.expect)(result.backupPath).toContain(backupDir);
         (0, import_vitest.expect)(result.backupPath).toContain("backup");
         const backupContent = await fs.readFile(result.backupPath, "utf-8");
         (0, import_vitest.expect)(backupContent).toBe("original content");
@@ -111,6 +114,7 @@ const createMockLogger = () => ({
             maxFileSize: 10 * 1024 * 1024,
             workingDirectory: tempDir,
             enableBackups: true,
+            backupPath: backupDir,
             backupRetentionDays: 7
           },
           mockLogger
@@ -133,6 +137,7 @@ const createMockLogger = () => ({
             workingDirectory: tempDir,
             enableBackups: false,
             // Config says no backups
+            backupPath: backupDir,
             backupRetentionDays: 7
           },
           mockLogger
@@ -157,6 +162,7 @@ const createMockLogger = () => ({
             maxFileSize: 10 * 1024 * 1024,
             workingDirectory: tempDir,
             enableBackups: false,
+            backupPath: backupDir,
             backupRetentionDays: 7
           },
           mockLogger
@@ -182,6 +188,7 @@ const createMockLogger = () => ({
             maxFileSize: 10 * 1024 * 1024,
             workingDirectory: tempDir,
             enableBackups: true,
+            backupPath: backupDir,
             backupRetentionDays: 7
           },
           mockLogger
@@ -210,6 +217,7 @@ const createMockLogger = () => ({
             workingDirectory: tempDir,
             enableBackups: false,
             // Config says no backups
+            backupPath: backupDir,
             backupRetentionDays: 7
           },
           mockLogger

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

@@ -1,2 +1,7 @@
-
-export {  }
+/**
+ * FileSystemService Tests
+ *
+ * Tests for the core filesystem service including backup behavior.
+ */
+export {};
+//# sourceMappingURL=filesystem-service.test.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"filesystem-service.test.d.ts","sourceRoot":"","sources":["../src/filesystem-service.test.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/dist/filesystem-service.test.js

@@ -13,10 +13,12 @@ const createMockLogger = () => ({
 describe("FileSystemService", () => {
   let mockLogger;
   let tempDir;
+  let backupDir;
   beforeEach(async () => {
     mockLogger = createMockLogger();
     const rawTempDir = await fs.mkdtemp(path.join(os.tmpdir(), "dexto-fs-test-"));
     tempDir = await fs.realpath(rawTempDir);
+    backupDir = path.join(tempDir, ".dexto", "backups");
     vi.clearAllMocks();
   });
   afterEach(async () => {
@@ -36,6 +38,7 @@ describe("FileSystemService", () => {
             maxFileSize: 10 * 1024 * 1024,
             workingDirectory: tempDir,
             enableBackups: false,
+            backupPath: backupDir,
             backupRetentionDays: 7
           },
           mockLogger
@@ -46,7 +49,6 @@ describe("FileSystemService", () => {
         const result = await fileSystemService.writeFile(testFile, "new content");
         expect(result.success).toBe(true);
         expect(result.backupPath).toBeUndefined();
-        const backupDir = path.join(tempDir, ".dexto-backups");
         try {
           const files = await fs.readdir(backupDir);
           expect(files.length).toBe(0);
@@ -62,6 +64,7 @@ describe("FileSystemService", () => {
             maxFileSize: 10 * 1024 * 1024,
             workingDirectory: tempDir,
             enableBackups: true,
+            backupPath: backupDir,
             backupRetentionDays: 7
           },
           mockLogger
@@ -72,7 +75,7 @@ describe("FileSystemService", () => {
         const result = await fileSystemService.writeFile(testFile, "new content");
         expect(result.success).toBe(true);
         expect(result.backupPath).toBeDefined();
-        expect(result.backupPath).toContain(".dexto");
+        expect(result.backupPath).toContain(backupDir);
         expect(result.backupPath).toContain("backup");
         const backupContent = await fs.readFile(result.backupPath, "utf-8");
         expect(backupContent).toBe("original content");
@@ -88,6 +91,7 @@ describe("FileSystemService", () => {
             maxFileSize: 10 * 1024 * 1024,
             workingDirectory: tempDir,
             enableBackups: true,
+            backupPath: backupDir,
             backupRetentionDays: 7
           },
           mockLogger
@@ -110,6 +114,7 @@ describe("FileSystemService", () => {
             workingDirectory: tempDir,
             enableBackups: false,
             // Config says no backups
+            backupPath: backupDir,
             backupRetentionDays: 7
           },
           mockLogger
@@ -134,6 +139,7 @@ describe("FileSystemService", () => {
             maxFileSize: 10 * 1024 * 1024,
             workingDirectory: tempDir,
             enableBackups: false,
+            backupPath: backupDir,
             backupRetentionDays: 7
           },
           mockLogger
@@ -159,6 +165,7 @@ describe("FileSystemService", () => {
             maxFileSize: 10 * 1024 * 1024,
             workingDirectory: tempDir,
             enableBackups: true,
+            backupPath: backupDir,
             backupRetentionDays: 7
           },
           mockLogger
@@ -187,6 +194,7 @@ describe("FileSystemService", () => {
             workingDirectory: tempDir,
             enableBackups: false,
             // Config says no backups
+            backupPath: backupDir,
             backupRetentionDays: 7
           },
           mockLogger