@dexto/tools-filesystem 1.5.0

package/dist/tool-provider.cjs

@@ -0,0 +1,108 @@
+"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 tool_provider_exports = {};
+__export(tool_provider_exports, {
+  fileSystemToolsProvider: () => fileSystemToolsProvider
+});
+module.exports = __toCommonJS(tool_provider_exports);
+var import_zod = require("zod");
+var import_filesystem_service = require("./filesystem-service.js");
+var import_read_file_tool = require("./read-file-tool.js");
+var import_write_file_tool = require("./write-file-tool.js");
+var import_edit_file_tool = require("./edit-file-tool.js");
+var import_glob_files_tool = require("./glob-files-tool.js");
+var import_grep_content_tool = require("./grep-content-tool.js");
+const DEFAULT_ALLOWED_PATHS = ["."];
+const DEFAULT_BLOCKED_PATHS = [".git", "node_modules/.bin", ".env"];
+const DEFAULT_BLOCKED_EXTENSIONS = [".exe", ".dll", ".so"];
+const DEFAULT_MAX_FILE_SIZE = 10 * 1024 * 1024;
+const DEFAULT_ENABLE_BACKUPS = false;
+const DEFAULT_BACKUP_RETENTION_DAYS = 7;
+const FileSystemToolsConfigSchema = import_zod.z.object({
+  type: import_zod.z.literal("filesystem-tools"),
+  allowedPaths: import_zod.z.array(import_zod.z.string()).default(DEFAULT_ALLOWED_PATHS).describe("List of allowed base paths for file operations"),
+  blockedPaths: import_zod.z.array(import_zod.z.string()).default(DEFAULT_BLOCKED_PATHS).describe("List of blocked paths to exclude from operations"),
+  blockedExtensions: import_zod.z.array(import_zod.z.string()).default(DEFAULT_BLOCKED_EXTENSIONS).describe("List of blocked file extensions"),
+  maxFileSize: import_zod.z.number().int().positive().default(DEFAULT_MAX_FILE_SIZE).describe(
+    `Maximum file size in bytes (default: ${DEFAULT_MAX_FILE_SIZE / 1024 / 1024}MB)`
+  ),
+  workingDirectory: import_zod.z.string().optional().describe("Working directory for file operations (defaults to process.cwd())"),
+  enableBackups: import_zod.z.boolean().default(DEFAULT_ENABLE_BACKUPS).describe("Enable automatic backups of modified files"),
+  backupPath: import_zod.z.string().optional().describe("Absolute path for storing file backups (if enableBackups is true)"),
+  backupRetentionDays: import_zod.z.number().int().positive().default(DEFAULT_BACKUP_RETENTION_DAYS).describe(
+    `Number of days to retain backup files (default: ${DEFAULT_BACKUP_RETENTION_DAYS})`
+  )
+}).strict();
+const fileSystemToolsProvider = {
+  type: "filesystem-tools",
+  configSchema: FileSystemToolsConfigSchema,
+  create: (config, context) => {
+    const { logger, services } = context;
+    logger.debug("Creating FileSystemService for filesystem tools");
+    const fileSystemService = new import_filesystem_service.FileSystemService(
+      {
+        allowedPaths: config.allowedPaths,
+        blockedPaths: config.blockedPaths,
+        blockedExtensions: config.blockedExtensions,
+        maxFileSize: config.maxFileSize,
+        workingDirectory: config.workingDirectory || process.cwd(),
+        enableBackups: config.enableBackups,
+        backupPath: config.backupPath,
+        backupRetentionDays: config.backupRetentionDays
+      },
+      logger
+    );
+    fileSystemService.initialize().catch((error) => {
+      logger.error(`Failed to initialize FileSystemService: ${error.message}`);
+    });
+    logger.debug("FileSystemService created - initialization will complete on first tool use");
+    const approvalManager = services?.approvalManager;
+    if (approvalManager) {
+      const approvalChecker = (filePath) => {
+        return approvalManager.isDirectoryApproved(filePath);
+      };
+      fileSystemService.setDirectoryApprovalChecker(approvalChecker);
+      logger.debug("Directory approval checker configured for FileSystemService");
+    }
+    const directoryApproval = approvalManager ? {
+      isSessionApproved: (filePath) => approvalManager.isDirectorySessionApproved(filePath),
+      addApproved: (directory, type) => approvalManager.addApprovedDirectory(directory, type)
+    } : void 0;
+    const fileToolOptions = {
+      fileSystemService,
+      directoryApproval
+    };
+    return [
+      (0, import_read_file_tool.createReadFileTool)(fileToolOptions),
+      (0, import_write_file_tool.createWriteFileTool)(fileToolOptions),
+      (0, import_edit_file_tool.createEditFileTool)(fileToolOptions),
+      (0, import_glob_files_tool.createGlobFilesTool)(fileSystemService),
+      (0, import_grep_content_tool.createGrepContentTool)(fileSystemService)
+    ];
+  },
+  metadata: {
+    displayName: "FileSystem Tools",
+    description: "File system operations (read, write, edit, glob, grep)",
+    category: "filesystem"
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  fileSystemToolsProvider
+});

package/dist/tool-provider.d.cts

@@ -0,0 +1,74 @@
+import { z } from 'zod';
+import { CustomToolProvider } from '@dexto/core';
+export { FileToolOptions } from './file-tool-types.cjs';
+import './filesystem-service.cjs';
+import './types.cjs';
+
+/**
+ * FileSystem Tools Provider
+ *
+ * Provides file operation tools by wrapping FileSystemService.
+ * When registered, the provider initializes FileSystemService and creates tools
+ * for file operations (read, write, edit, glob, grep).
+ */
+
+/**
+ * Configuration schema for FileSystem tools provider.
+ *
+ * This is the SINGLE SOURCE OF TRUTH for all configuration:
+ * - Validation rules
+ * - Default values (using constants above)
+ * - Documentation
+ * - Type definitions
+ *
+ * Services receive fully-validated config from this schema and use it as-is,
+ * with no additional defaults or fallbacks needed.
+ */
+declare const FileSystemToolsConfigSchema: z.ZodObject<{
+    type: z.ZodLiteral<"filesystem-tools">;
+    allowedPaths: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    blockedPaths: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    blockedExtensions: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    maxFileSize: z.ZodDefault<z.ZodNumber>;
+    workingDirectory: z.ZodOptional<z.ZodString>;
+    enableBackups: z.ZodDefault<z.ZodBoolean>;
+    backupPath: z.ZodOptional<z.ZodString>;
+    backupRetentionDays: z.ZodDefault<z.ZodNumber>;
+}, "strict", z.ZodTypeAny, {
+    type: "filesystem-tools";
+    allowedPaths: string[];
+    blockedExtensions: string[];
+    blockedPaths: string[];
+    maxFileSize: number;
+    enableBackups: boolean;
+    backupRetentionDays: number;
+    backupPath?: string | undefined;
+    workingDirectory?: string | undefined;
+}, {
+    type: "filesystem-tools";
+    allowedPaths?: string[] | undefined;
+    blockedExtensions?: string[] | undefined;
+    backupPath?: string | undefined;
+    blockedPaths?: string[] | undefined;
+    maxFileSize?: number | undefined;
+    enableBackups?: boolean | undefined;
+    backupRetentionDays?: number | undefined;
+    workingDirectory?: string | undefined;
+}>;
+type FileSystemToolsConfig = z.output<typeof FileSystemToolsConfigSchema>;
+/**
+ * FileSystem tools provider.
+ *
+ * Wraps FileSystemService and provides file operation tools:
+ * - read_file: Read file contents with pagination
+ * - write_file: Write or overwrite file contents
+ * - edit_file: Edit files using search/replace operations
+ * - glob_files: Find files matching glob patterns
+ * - grep_content: Search file contents using regex
+ *
+ * When registered via customToolRegistry, FileSystemService is automatically
+ * initialized and file operation tools become available to the agent.
+ */
+declare const fileSystemToolsProvider: CustomToolProvider<'filesystem-tools', FileSystemToolsConfig>;
+
+export { fileSystemToolsProvider };

package/dist/tool-provider.d.ts

@@ -0,0 +1,74 @@
+import { z } from 'zod';
+import { CustomToolProvider } from '@dexto/core';
+export { FileToolOptions } from './file-tool-types.js';
+import './filesystem-service.js';
+import './types.js';
+
+/**
+ * FileSystem Tools Provider
+ *
+ * Provides file operation tools by wrapping FileSystemService.
+ * When registered, the provider initializes FileSystemService and creates tools
+ * for file operations (read, write, edit, glob, grep).
+ */
+
+/**
+ * Configuration schema for FileSystem tools provider.
+ *
+ * This is the SINGLE SOURCE OF TRUTH for all configuration:
+ * - Validation rules
+ * - Default values (using constants above)
+ * - Documentation
+ * - Type definitions
+ *
+ * Services receive fully-validated config from this schema and use it as-is,
+ * with no additional defaults or fallbacks needed.
+ */
+declare const FileSystemToolsConfigSchema: z.ZodObject<{
+    type: z.ZodLiteral<"filesystem-tools">;
+    allowedPaths: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    blockedPaths: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    blockedExtensions: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    maxFileSize: z.ZodDefault<z.ZodNumber>;
+    workingDirectory: z.ZodOptional<z.ZodString>;
+    enableBackups: z.ZodDefault<z.ZodBoolean>;
+    backupPath: z.ZodOptional<z.ZodString>;
+    backupRetentionDays: z.ZodDefault<z.ZodNumber>;
+}, "strict", z.ZodTypeAny, {
+    type: "filesystem-tools";
+    allowedPaths: string[];
+    blockedExtensions: string[];
+    blockedPaths: string[];
+    maxFileSize: number;
+    enableBackups: boolean;
+    backupRetentionDays: number;
+    backupPath?: string | undefined;
+    workingDirectory?: string | undefined;
+}, {
+    type: "filesystem-tools";
+    allowedPaths?: string[] | undefined;
+    blockedExtensions?: string[] | undefined;
+    backupPath?: string | undefined;
+    blockedPaths?: string[] | undefined;
+    maxFileSize?: number | undefined;
+    enableBackups?: boolean | undefined;
+    backupRetentionDays?: number | undefined;
+    workingDirectory?: string | undefined;
+}>;
+type FileSystemToolsConfig = z.output<typeof FileSystemToolsConfigSchema>;
+/**
+ * FileSystem tools provider.
+ *
+ * Wraps FileSystemService and provides file operation tools:
+ * - read_file: Read file contents with pagination
+ * - write_file: Write or overwrite file contents
+ * - edit_file: Edit files using search/replace operations
+ * - glob_files: Find files matching glob patterns
+ * - grep_content: Search file contents using regex
+ *
+ * When registered via customToolRegistry, FileSystemService is automatically
+ * initialized and file operation tools become available to the agent.
+ */
+declare const fileSystemToolsProvider: CustomToolProvider<'filesystem-tools', FileSystemToolsConfig>;
+
+export { fileSystemToolsProvider };

package/dist/tool-provider.js

@@ -0,0 +1,84 @@
+import { z } from "zod";
+import { FileSystemService } from "./filesystem-service.js";
+import { createReadFileTool } from "./read-file-tool.js";
+import { createWriteFileTool } from "./write-file-tool.js";
+import { createEditFileTool } from "./edit-file-tool.js";
+import { createGlobFilesTool } from "./glob-files-tool.js";
+import { createGrepContentTool } from "./grep-content-tool.js";
+const DEFAULT_ALLOWED_PATHS = ["."];
+const DEFAULT_BLOCKED_PATHS = [".git", "node_modules/.bin", ".env"];
+const DEFAULT_BLOCKED_EXTENSIONS = [".exe", ".dll", ".so"];
+const DEFAULT_MAX_FILE_SIZE = 10 * 1024 * 1024;
+const DEFAULT_ENABLE_BACKUPS = false;
+const DEFAULT_BACKUP_RETENTION_DAYS = 7;
+const FileSystemToolsConfigSchema = z.object({
+  type: z.literal("filesystem-tools"),
+  allowedPaths: z.array(z.string()).default(DEFAULT_ALLOWED_PATHS).describe("List of allowed base paths for file operations"),
+  blockedPaths: z.array(z.string()).default(DEFAULT_BLOCKED_PATHS).describe("List of blocked paths to exclude from operations"),
+  blockedExtensions: z.array(z.string()).default(DEFAULT_BLOCKED_EXTENSIONS).describe("List of blocked file extensions"),
+  maxFileSize: z.number().int().positive().default(DEFAULT_MAX_FILE_SIZE).describe(
+    `Maximum file size in bytes (default: ${DEFAULT_MAX_FILE_SIZE / 1024 / 1024}MB)`
+  ),
+  workingDirectory: z.string().optional().describe("Working directory for file operations (defaults to process.cwd())"),
+  enableBackups: z.boolean().default(DEFAULT_ENABLE_BACKUPS).describe("Enable automatic backups of modified files"),
+  backupPath: z.string().optional().describe("Absolute path for storing file backups (if enableBackups is true)"),
+  backupRetentionDays: z.number().int().positive().default(DEFAULT_BACKUP_RETENTION_DAYS).describe(
+    `Number of days to retain backup files (default: ${DEFAULT_BACKUP_RETENTION_DAYS})`
+  )
+}).strict();
+const fileSystemToolsProvider = {
+  type: "filesystem-tools",
+  configSchema: FileSystemToolsConfigSchema,
+  create: (config, context) => {
+    const { logger, services } = context;
+    logger.debug("Creating FileSystemService for filesystem tools");
+    const fileSystemService = new FileSystemService(
+      {
+        allowedPaths: config.allowedPaths,
+        blockedPaths: config.blockedPaths,
+        blockedExtensions: config.blockedExtensions,
+        maxFileSize: config.maxFileSize,
+        workingDirectory: config.workingDirectory || process.cwd(),
+        enableBackups: config.enableBackups,
+        backupPath: config.backupPath,
+        backupRetentionDays: config.backupRetentionDays
+      },
+      logger
+    );
+    fileSystemService.initialize().catch((error) => {
+      logger.error(`Failed to initialize FileSystemService: ${error.message}`);
+    });
+    logger.debug("FileSystemService created - initialization will complete on first tool use");
+    const approvalManager = services?.approvalManager;
+    if (approvalManager) {
+      const approvalChecker = (filePath) => {
+        return approvalManager.isDirectoryApproved(filePath);
+      };
+      fileSystemService.setDirectoryApprovalChecker(approvalChecker);
+      logger.debug("Directory approval checker configured for FileSystemService");
+    }
+    const directoryApproval = approvalManager ? {
+      isSessionApproved: (filePath) => approvalManager.isDirectorySessionApproved(filePath),
+      addApproved: (directory, type) => approvalManager.addApprovedDirectory(directory, type)
+    } : void 0;
+    const fileToolOptions = {
+      fileSystemService,
+      directoryApproval
+    };
+    return [
+      createReadFileTool(fileToolOptions),
+      createWriteFileTool(fileToolOptions),
+      createEditFileTool(fileToolOptions),
+      createGlobFilesTool(fileSystemService),
+      createGrepContentTool(fileSystemService)
+    ];
+  },
+  metadata: {
+    displayName: "FileSystem Tools",
+    description: "File system operations (read, write, edit, glob, grep)",
+    category: "filesystem"
+  }
+};
+export {
+  fileSystemToolsProvider
+};

package/dist/types.cjs

@@ -0,0 +1,16 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+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 types_exports = {};
+module.exports = __toCommonJS(types_exports);

package/dist/types.d.cts

@@ -0,0 +1,172 @@
+/**
+ * FileSystem Service Types
+ *
+ * Types and interfaces for file system operations including reading, writing,
+ * searching, and validation.
+ */
+type BufferEncoding = 'ascii' | 'utf8' | 'utf-8' | 'utf16le' | 'ucs2' | 'ucs-2' | 'base64' | 'base64url' | 'latin1' | 'binary' | 'hex';
+/**
+ * File content with metadata
+ */
+interface FileContent {
+    content: string;
+    lines: number;
+    encoding: string;
+    mimeType?: string;
+    truncated: boolean;
+    size: number;
+}
+/**
+ * Options for reading files
+ */
+interface ReadFileOptions {
+    /** Maximum number of lines to read */
+    limit?: number | undefined;
+    /** Starting line number (1-based) */
+    offset?: number | undefined;
+    /** File encoding (default: utf-8) */
+    encoding?: BufferEncoding | undefined;
+}
+/**
+ * File metadata for glob results
+ */
+interface FileMetadata {
+    path: string;
+    size: number;
+    modified: Date;
+    isDirectory: boolean;
+}
+/**
+ * Options for glob operations
+ */
+interface GlobOptions {
+    /** Base directory to search from */
+    cwd?: string | undefined;
+    /** Maximum number of results */
+    maxResults?: number | undefined;
+    /** Include file metadata */
+    includeMetadata?: boolean | undefined;
+}
+/**
+ * Glob result
+ */
+interface GlobResult {
+    files: FileMetadata[];
+    truncated: boolean;
+    totalFound: number;
+}
+/**
+ * Search match with context
+ */
+interface SearchMatch {
+    file: string;
+    lineNumber: number;
+    line: string;
+    context?: {
+        before: string[];
+        after: string[];
+    };
+}
+/**
+ * Options for content search (grep)
+ */
+interface GrepOptions {
+    /** Base directory to search */
+    path?: string | undefined;
+    /** Glob pattern to filter files */
+    glob?: string | undefined;
+    /** Number of context lines before/after match */
+    contextLines?: number | undefined;
+    /** Case-insensitive search */
+    caseInsensitive?: boolean | undefined;
+    /** Maximum number of results */
+    maxResults?: number | undefined;
+    /** Include line numbers */
+    lineNumbers?: boolean | undefined;
+}
+/**
+ * Search result
+ */
+interface SearchResult {
+    matches: SearchMatch[];
+    totalMatches: number;
+    truncated: boolean;
+    filesSearched: number;
+}
+/**
+ * Options for writing files
+ */
+interface WriteFileOptions {
+    /** Create parent directories if they don't exist */
+    createDirs?: boolean | undefined;
+    /** File encoding (default: utf-8) */
+    encoding?: BufferEncoding | undefined;
+    /** Create backup before overwriting */
+    backup?: boolean | undefined;
+}
+/**
+ * Write result
+ */
+interface WriteResult {
+    success: boolean;
+    path: string;
+    bytesWritten: number;
+    backupPath?: string | undefined;
+}
+/**
+ * Edit operation
+ */
+interface EditOperation {
+    oldString: string;
+    newString: string;
+    replaceAll?: boolean | undefined;
+}
+/**
+ * Options for editing files
+ */
+interface EditFileOptions {
+    /** Create backup before editing */
+    backup?: boolean;
+    /** File encoding */
+    encoding?: BufferEncoding;
+}
+/**
+ * Edit result
+ */
+interface EditResult {
+    success: boolean;
+    path: string;
+    changesCount: number;
+    backupPath?: string | undefined;
+}
+/**
+ * Path validation result
+ */
+interface PathValidation {
+    isValid: boolean;
+    error?: string;
+    normalizedPath?: string;
+}
+/**
+ * File system configuration
+ */
+interface FileSystemConfig {
+    /** Allowed base paths */
+    allowedPaths: string[];
+    /** Blocked paths (relative to allowed paths) */
+    blockedPaths: string[];
+    /** Blocked file extensions */
+    blockedExtensions: string[];
+    /** Maximum file size in bytes */
+    maxFileSize: number;
+    /** Enable automatic backups */
+    enableBackups: boolean;
+    /** Backup directory absolute path (required when enableBackups is true - provided by CLI enrichment) */
+    backupPath?: string | undefined;
+    /** Backup retention period in days (default: 7) */
+    backupRetentionDays: number;
+    /** Working directory for glob/grep operations (defaults to process.cwd()) */
+    workingDirectory?: string | undefined;
+}
+
+export type { BufferEncoding, EditFileOptions, EditOperation, EditResult, FileContent, FileMetadata, FileSystemConfig, GlobOptions, GlobResult, GrepOptions, PathValidation, ReadFileOptions, SearchMatch, SearchResult, WriteFileOptions, WriteResult };