@dexto/tools-filesystem 1.5.0

package/dist/filesystem-service.d.ts

@@ -0,0 +1,107 @@
+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
+ */
+
+/**
+ * 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
+ * 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 {
+    private config;
+    private pathValidator;
+    private initialized;
+    private initPromise;
+    private logger;
+    /**
+     * Create a new FileSystemService with validated configuration.
+     *
+     * @param config - Fully-validated configuration from provider schema.
+     *                 All required fields have values, defaults already applied.
+     * @param logger - Logger instance for this service
+     */
+    constructor(config: FileSystemConfig, logger: IDextoLogger);
+    /**
+     * Get backup directory path (context-aware with optional override)
+     * TODO: Migrate to explicit configuration via CLI enrichment layer (per-agent paths)
+     */
+    private getBackupDir;
+    /**
+     * Initialize the service.
+     * Safe to call multiple times - subsequent calls return the same promise.
+     */
+    initialize(): Promise<void>;
+    /**
+     * Internal initialization logic.
+     */
+    private doInitialize;
+    /**
+     * Ensure the service is initialized before use.
+     * Tools should call this at the start of their execute methods.
+     * Safe to call multiple times - will await the same initialization promise.
+     */
+    ensureInitialized(): Promise<void>;
+    /**
+     * Set a callback to check if a path is in an approved directory.
+     * This allows PathValidator to consult ApprovalManager without a direct dependency.
+     *
+     * @param checker Function that returns true if path is in an approved directory
+     */
+    setDirectoryApprovalChecker(checker: (filePath: string) => boolean): 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.
+     *
+     * @param filePath The file path to check (can be relative or absolute)
+     * @returns true if the path is within config-allowed paths, false otherwise
+     */
+    isPathWithinConfigAllowed(filePath: string): boolean;
+    /**
+     * Read a file with validation and size limits
+     */
+    readFile(filePath: string, options?: ReadFileOptions): Promise<FileContent>;
+    /**
+     * Find files matching a glob pattern
+     */
+    globFiles(pattern: string, options?: GlobOptions): Promise<GlobResult>;
+    /**
+     * Search for content in files (grep-like functionality)
+     */
+    searchContent(pattern: string, options?: GrepOptions): Promise<SearchResult>;
+    /**
+     * Write content to a file
+     */
+    writeFile(filePath: string, content: string, options?: WriteFileOptions): Promise<WriteResult>;
+    /**
+     * Edit a file by replacing text
+     */
+    editFile(filePath: string, operation: EditOperation, options?: EditFileOptions): Promise<EditResult>;
+    /**
+     * Create a backup of a file
+     */
+    private createBackup;
+    /**
+     * Clean up old backup files based on retention policy
+     */
+    cleanupOldBackups(): Promise<number>;
+    /**
+     * Get service configuration
+     */
+    getConfig(): Readonly<FileSystemConfig>;
+    /**
+     * Check if a path is allowed
+     */
+    isPathAllowed(filePath: string): boolean;
+}
+
+export { FileSystemService };

package/dist/filesystem-service.js

@@ -0,0 +1,492 @@
+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 { 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;
+class FileSystemService {
+  config;
+  pathValidator;
+  initialized = false;
+  initPromise = null;
+  logger;
+  /**
+   * Create a new FileSystemService with validated configuration.
+   *
+   * @param config - Fully-validated configuration from provider schema.
+   *                 All required fields have values, defaults already applied.
+   * @param logger - Logger instance for this service
+   */
+  constructor(config, logger) {
+    this.config = config;
+    this.logger = logger.createChild(DextoLogComponent.FILESYSTEM);
+    this.pathValidator = new PathValidator(this.config, this.logger);
+  }
+  /**
+   * Get backup directory path (context-aware with optional override)
+   * TODO: Migrate to explicit configuration via CLI enrichment layer (per-agent paths)
+   */
+  getBackupDir() {
+    return this.config.backupPath || getDextoPath("backups");
+  }
+  /**
+   * Initialize the service.
+   * Safe to call multiple times - subsequent calls return the same promise.
+   */
+  initialize() {
+    if (this.initPromise) {
+      return this.initPromise;
+    }
+    this.initPromise = this.doInitialize();
+    return this.initPromise;
+  }
+  /**
+   * Internal initialization logic.
+   */
+  async doInitialize() {
+    if (this.initialized) {
+      this.logger.debug("FileSystemService already initialized");
+      return;
+    }
+    if (this.config.enableBackups) {
+      try {
+        const backupDir = this.getBackupDir();
+        await fs.mkdir(backupDir, { recursive: true });
+        this.logger.debug(`Backup directory created/verified: ${backupDir}`);
+      } catch (error) {
+        this.logger.warn(
+          `Failed to create backup directory: ${error instanceof Error ? error.message : String(error)}`
+        );
+      }
+    }
+    this.initialized = true;
+    this.logger.info("FileSystemService initialized successfully");
+  }
+  /**
+   * Ensure the service is initialized before use.
+   * Tools should call this at the start of their execute methods.
+   * Safe to call multiple times - will await the same initialization promise.
+   */
+  async ensureInitialized() {
+    if (this.initialized) {
+      return;
+    }
+    await this.initialize();
+  }
+  /**
+   * Set a callback to check if a path is in an approved directory.
+   * This allows PathValidator to consult ApprovalManager without a direct dependency.
+   *
+   * @param checker Function that returns true if path is in an approved directory
+   */
+  setDirectoryApprovalChecker(checker) {
+    this.pathValidator.setDirectoryApprovalChecker(checker);
+  }
+  /**
+   * 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.
+   *
+   * @param filePath The file path to check (can be relative or absolute)
+   * @returns true if the path is within config-allowed paths, false otherwise
+   */
+  isPathWithinConfigAllowed(filePath) {
+    return this.pathValidator.isPathWithinAllowed(filePath);
+  }
+  /**
+   * Read a file with validation and size limits
+   */
+  async readFile(filePath, options = {}) {
+    await this.ensureInitialized();
+    const validation = this.pathValidator.validatePath(filePath);
+    if (!validation.isValid || !validation.normalizedPath) {
+      throw FileSystemError.invalidPath(filePath, validation.error || "Unknown error");
+    }
+    const normalizedPath = validation.normalizedPath;
+    try {
+      const stats = await fs.stat(normalizedPath);
+      if (!stats.isFile()) {
+        throw FileSystemError.invalidPath(normalizedPath, "Path is not a file");
+      }
+      if (stats.size > this.config.maxFileSize) {
+        throw FileSystemError.fileTooLarge(
+          normalizedPath,
+          stats.size,
+          this.config.maxFileSize
+        );
+      }
+    } catch (error) {
+      if (error.code === "ENOENT") {
+        throw FileSystemError.fileNotFound(normalizedPath);
+      }
+      if (error.code === "EACCES") {
+        throw FileSystemError.permissionDenied(normalizedPath, "read");
+      }
+      throw FileSystemError.readFailed(
+        normalizedPath,
+        error instanceof Error ? error.message : String(error)
+      );
+    }
+    try {
+      const encoding = options.encoding || DEFAULT_ENCODING;
+      const content = await fs.readFile(normalizedPath, encoding);
+      const lines = content.split("\n");
+      const limit = options.limit;
+      const offset1 = options.offset;
+      let selectedLines;
+      let truncated = false;
+      if (offset1 && offset1 > 0 || limit !== void 0) {
+        const start = offset1 && offset1 > 0 ? Math.max(0, offset1 - 1) : 0;
+        const end = limit !== void 0 ? start + limit : lines.length;
+        selectedLines = lines.slice(start, end);
+        truncated = end < lines.length;
+      } else {
+        selectedLines = lines;
+      }
+      return {
+        content: selectedLines.join("\n"),
+        lines: selectedLines.length,
+        encoding,
+        truncated,
+        size: Buffer.byteLength(content, encoding)
+      };
+    } catch (error) {
+      throw FileSystemError.readFailed(
+        normalizedPath,
+        error instanceof Error ? error.message : String(error)
+      );
+    }
+  }
+  /**
+   * Find files matching a glob pattern
+   */
+  async globFiles(pattern, options = {}) {
+    await this.ensureInitialized();
+    const cwd = options.cwd || this.config.workingDirectory || process.cwd();
+    const maxResults = options.maxResults || DEFAULT_MAX_RESULTS;
+    try {
+      const files = await glob(pattern, {
+        cwd,
+        absolute: true,
+        nodir: true,
+        // Only files
+        follow: false
+        // Don't follow symlinks
+      });
+      const validFiles = [];
+      for (const file of files) {
+        const validation = this.pathValidator.validatePath(file);
+        if (!validation.isValid || !validation.normalizedPath) {
+          this.logger.debug(`Skipping invalid path: ${file}`);
+          continue;
+        }
+        if (options.includeMetadata !== false) {
+          try {
+            const stats = await fs.stat(validation.normalizedPath);
+            validFiles.push({
+              path: validation.normalizedPath,
+              size: stats.size,
+              modified: stats.mtime,
+              isDirectory: stats.isDirectory()
+            });
+          } catch (error) {
+            this.logger.debug(
+              `Failed to stat file ${file}: ${error instanceof Error ? error.message : String(error)}`
+            );
+          }
+        } else {
+          validFiles.push({
+            path: validation.normalizedPath,
+            size: 0,
+            modified: /* @__PURE__ */ new Date(),
+            isDirectory: false
+          });
+        }
+        if (validFiles.length >= maxResults) {
+          break;
+        }
+      }
+      const limited = validFiles.length >= maxResults;
+      return {
+        files: validFiles,
+        truncated: limited,
+        totalFound: validFiles.length
+      };
+    } catch (error) {
+      throw FileSystemError.globFailed(
+        pattern,
+        error instanceof Error ? error.message : String(error)
+      );
+    }
+  }
+  /**
+   * Search for content in files (grep-like functionality)
+   */
+  async searchContent(pattern, options = {}) {
+    await this.ensureInitialized();
+    const searchPath = options.path || this.config.workingDirectory || process.cwd();
+    const globPattern = options.glob || "**/*";
+    const maxResults = options.maxResults || DEFAULT_MAX_SEARCH_RESULTS;
+    const contextLines = options.contextLines || 0;
+    try {
+      if (!safeRegex(pattern)) {
+        throw FileSystemError.invalidPattern(
+          pattern,
+          "Pattern may cause catastrophic backtracking (ReDoS). Please simplify the regex."
+        );
+      }
+      const flags = options.caseInsensitive ? "i" : "";
+      const regex = new RegExp(pattern, flags);
+      const globResult = await this.globFiles(globPattern, {
+        cwd: searchPath,
+        maxResults: 1e4
+        // Search more files, but limit results
+      });
+      const matches = [];
+      let filesSearched = 0;
+      for (const fileInfo of globResult.files) {
+        try {
+          const fileContent = await this.readFile(fileInfo.path);
+          const lines = fileContent.content.split("\n");
+          filesSearched++;
+          for (let i = 0; i < lines.length; i++) {
+            const line = lines[i];
+            if (regex.test(line)) {
+              let context;
+              if (contextLines > 0) {
+                const before = [];
+                const after = [];
+                for (let j = Math.max(0, i - contextLines); j < i; j++) {
+                  before.push(lines[j]);
+                }
+                for (let j = i + 1; j < Math.min(lines.length, i + contextLines + 1); j++) {
+                  after.push(lines[j]);
+                }
+                context = { before, after };
+              }
+              matches.push({
+                file: fileInfo.path,
+                lineNumber: i + 1,
+                // 1-based line numbers
+                line,
+                ...context !== void 0 && { context }
+              });
+              if (matches.length >= maxResults) {
+                return {
+                  matches,
+                  totalMatches: matches.length,
+                  truncated: true,
+                  filesSearched
+                };
+              }
+            }
+          }
+        } catch (error) {
+          this.logger.debug(
+            `Skipping file ${fileInfo.path}: ${error instanceof Error ? error.message : String(error)}`
+          );
+        }
+      }
+      return {
+        matches,
+        totalMatches: matches.length,
+        truncated: false,
+        filesSearched
+      };
+    } catch (error) {
+      if (error instanceof Error && error.message.includes("Invalid regular expression")) {
+        throw FileSystemError.invalidPattern(pattern, "Invalid regular expression syntax");
+      }
+      throw FileSystemError.searchFailed(
+        pattern,
+        error instanceof Error ? error.message : String(error)
+      );
+    }
+  }
+  /**
+   * Write content to a file
+   */
+  async writeFile(filePath, content, options = {}) {
+    await this.ensureInitialized();
+    const validation = this.pathValidator.validatePath(filePath);
+    if (!validation.isValid || !validation.normalizedPath) {
+      throw FileSystemError.invalidPath(filePath, validation.error || "Unknown error");
+    }
+    const normalizedPath = validation.normalizedPath;
+    const encoding = options.encoding || DEFAULT_ENCODING;
+    let backupPath;
+    let fileExists = false;
+    try {
+      await fs.access(normalizedPath);
+      fileExists = true;
+    } catch {
+    }
+    if (fileExists && (options.backup ?? this.config.enableBackups)) {
+      backupPath = await this.createBackup(normalizedPath);
+    }
+    try {
+      if (options.createDirs) {
+        const dir = path.dirname(normalizedPath);
+        await fs.mkdir(dir, { recursive: true });
+      }
+      await fs.writeFile(normalizedPath, content, encoding);
+      const bytesWritten = Buffer.byteLength(content, encoding);
+      this.logger.debug(`File written: ${normalizedPath} (${bytesWritten} bytes)`);
+      return {
+        success: true,
+        path: normalizedPath,
+        bytesWritten,
+        backupPath
+      };
+    } catch (error) {
+      throw FileSystemError.writeFailed(
+        normalizedPath,
+        error instanceof Error ? error.message : String(error)
+      );
+    }
+  }
+  /**
+   * Edit a file by replacing text
+   */
+  async editFile(filePath, operation, options = {}) {
+    await this.ensureInitialized();
+    const validation = this.pathValidator.validatePath(filePath);
+    if (!validation.isValid || !validation.normalizedPath) {
+      throw FileSystemError.invalidPath(filePath, validation.error || "Unknown error");
+    }
+    const normalizedPath = validation.normalizedPath;
+    const fileContent = await this.readFile(normalizedPath);
+    let content = fileContent.content;
+    const occurrences = (content.match(
+      new RegExp(operation.oldString.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"), "g")
+    ) || []).length;
+    if (occurrences === 0) {
+      throw FileSystemError.stringNotFound(normalizedPath, operation.oldString);
+    }
+    if (!operation.replaceAll && occurrences > 1) {
+      throw FileSystemError.stringNotUnique(normalizedPath, operation.oldString, occurrences);
+    }
+    let backupPath;
+    if (options.backup ?? this.config.enableBackups) {
+      backupPath = await this.createBackup(normalizedPath);
+    }
+    try {
+      if (operation.replaceAll) {
+        content = content.replace(
+          new RegExp(operation.oldString.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"), "g"),
+          operation.newString
+        );
+      } else {
+        content = content.replace(operation.oldString, operation.newString);
+      }
+      await fs.writeFile(normalizedPath, content, options.encoding || DEFAULT_ENCODING);
+      this.logger.debug(`File edited: ${normalizedPath} (${occurrences} replacements)`);
+      return {
+        success: true,
+        path: normalizedPath,
+        changesCount: occurrences,
+        backupPath
+      };
+    } catch (error) {
+      throw FileSystemError.editFailed(
+        normalizedPath,
+        error instanceof Error ? error.message : String(error)
+      );
+    }
+  }
+  /**
+   * Create a backup of a file
+   */
+  async createBackup(filePath) {
+    const backupDir = this.getBackupDir();
+    const timestamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
+    const basename = path.basename(filePath);
+    const backupFilename = `${basename}.${timestamp}.backup`;
+    const backupPath = path.join(backupDir, backupFilename);
+    try {
+      await fs.mkdir(backupDir, { recursive: true });
+      await fs.copyFile(filePath, backupPath);
+      this.logger.debug(`Backup created: ${backupPath}`);
+      await this.cleanupOldBackups();
+      return backupPath;
+    } catch (error) {
+      throw FileSystemError.backupFailed(
+        filePath,
+        error instanceof Error ? error.message : String(error)
+      );
+    }
+  }
+  /**
+   * Clean up old backup files based on retention policy
+   */
+  async cleanupOldBackups() {
+    if (!this.config.enableBackups) {
+      return 0;
+    }
+    let backupDir;
+    try {
+      backupDir = this.getBackupDir();
+    } catch (error) {
+      this.logger.warn(
+        `Failed to resolve backup directory: ${error instanceof Error ? error.message : String(error)}`
+      );
+      return 0;
+    }
+    try {
+      await fs.access(backupDir);
+    } catch {
+      return 0;
+    }
+    const cutoffDate = new Date(
+      Date.now() - this.config.backupRetentionDays * 24 * 60 * 60 * 1e3
+    );
+    let deletedCount = 0;
+    try {
+      const files = await fs.readdir(backupDir);
+      const backupFiles = files.filter((file) => file.endsWith(".backup"));
+      for (const file of backupFiles) {
+        const filePath = path.join(backupDir, file);
+        try {
+          const stats = await fs.stat(filePath);
+          if (stats.mtime < cutoffDate) {
+            await fs.unlink(filePath);
+            deletedCount++;
+            this.logger.debug(`Cleaned up old backup: ${file}`);
+          }
+        } catch (error) {
+          this.logger.warn(
+            `Failed to process backup file ${file}: ${error instanceof Error ? error.message : String(error)}`
+          );
+        }
+      }
+      if (deletedCount > 0) {
+        this.logger.info(`Backup cleanup: removed ${deletedCount} old backup files`);
+      }
+      return deletedCount;
+    } catch (error) {
+      this.logger.warn(
+        `Failed to cleanup backup directory: ${error instanceof Error ? error.message : String(error)}`
+      );
+      return 0;
+    }
+  }
+  /**
+   * Get service configuration
+   */
+  getConfig() {
+    return { ...this.config };
+  }
+  /**
+   * Check if a path is allowed
+   */
+  isPathAllowed(filePath) {
+    const validation = this.pathValidator.validatePath(filePath);
+    return validation.isValid;
+  }
+}
+export {
+  FileSystemService
+};

package/dist/glob-files-tool.cjs

@@ -0,0 +1,70 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var glob_files_tool_exports = {};
+__export(glob_files_tool_exports, {
+  createGlobFilesTool: () => createGlobFilesTool
+});
+module.exports = __toCommonJS(glob_files_tool_exports);
+var import_zod = require("zod");
+const GlobFilesInputSchema = import_zod.z.object({
+  pattern: import_zod.z.string().describe('Glob pattern to match files (e.g., "**/*.ts", "src/**/*.js")'),
+  path: import_zod.z.string().optional().describe("Base directory to search from (defaults to working directory)"),
+  max_results: import_zod.z.number().int().positive().optional().default(1e3).describe("Maximum number of results to return (default: 1000)")
+}).strict();
+function createGlobFilesTool(fileSystemService) {
+  return {
+    id: "glob_files",
+    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,
+    execute: async (input, _context) => {
+      const { pattern, path, max_results } = input;
+      const result = await fileSystemService.globFiles(pattern, {
+        cwd: path,
+        maxResults: max_results,
+        includeMetadata: true
+      });
+      const _display = {
+        type: "search",
+        pattern,
+        matches: result.files.map((file) => ({
+          file: file.path,
+          line: 0,
+          // No line number for glob
+          content: file.path
+        })),
+        totalMatches: result.totalFound,
+        truncated: result.truncated
+      };
+      return {
+        files: result.files.map((file) => ({
+          path: file.path,
+          size: file.size,
+          modified: file.modified.toISOString()
+        })),
+        total_found: result.totalFound,
+        truncated: result.truncated,
+        _display
+      };
+    }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createGlobFilesTool
+});

package/dist/glob-files-tool.d.cts

@@ -0,0 +1,16 @@
+import { InternalTool } from '@dexto/core';
+import { FileSystemService } from './filesystem-service.cjs';
+import './types.cjs';
+
+/**
+ * Glob Files Tool
+ *
+ * Internal tool for finding files using glob patterns
+ */
+
+/**
+ * Create the glob_files internal tool
+ */
+declare function createGlobFilesTool(fileSystemService: FileSystemService): InternalTool;
+
+export { createGlobFilesTool };

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

@@ -0,0 +1,16 @@
+import { InternalTool } from '@dexto/core';
+import { FileSystemService } from './filesystem-service.js';
+import './types.js';
+
+/**
+ * Glob Files Tool
+ *
+ * Internal tool for finding files using glob patterns
+ */
+
+/**
+ * Create the glob_files internal tool
+ */
+declare function createGlobFilesTool(fileSystemService: FileSystemService): InternalTool;
+
+export { createGlobFilesTool };