@dexto/tools-filesystem 1.5.0

package/dist/types.d.ts

@@ -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 };

package/dist/write-file-tool.cjs

@@ -0,0 +1,177 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+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 __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var write_file_tool_exports = {};
+__export(write_file_tool_exports, {
+  createWriteFileTool: () => createWriteFileTool
+});
+module.exports = __toCommonJS(write_file_tool_exports);
+var path = __toESM(require("node:path"), 1);
+var import_zod = require("zod");
+var import_diff = require("diff");
+var import_core = require("@dexto/core");
+var import_error_codes = require("./error-codes.js");
+const WriteFileInputSchema = import_zod.z.object({
+  file_path: import_zod.z.string().describe("Absolute path where the file should be written"),
+  content: import_zod.z.string().describe("Content to write to the file"),
+  create_dirs: import_zod.z.boolean().optional().default(false).describe("Create parent directories if they don't exist (default: false)"),
+  encoding: import_zod.z.enum(["utf-8", "ascii", "latin1", "utf16le"]).optional().default("utf-8").describe("File encoding (default: utf-8)")
+}).strict();
+function generateDiffPreview(filePath, originalContent, newContent) {
+  const unified = (0, import_diff.createPatch)(filePath, originalContent, newContent, "before", "after", {
+    context: 3
+  });
+  const additions = (unified.match(/^\+[^+]/gm) || []).length;
+  const deletions = (unified.match(/^-[^-]/gm) || []).length;
+  return {
+    type: "diff",
+    unified,
+    filename: filePath,
+    additions,
+    deletions
+  };
+}
+function createWriteFileTool(options) {
+  const { fileSystemService, directoryApproval } = options;
+  let pendingApprovalParentDir;
+  return {
+    id: "write_file",
+    description: "Write content to a file. Creates a new file or overwrites existing file. Automatically creates backup of existing files before overwriting. Use create_dirs to create parent directories. Requires approval for all write operations. Returns success status, path, bytes written, and backup path if applicable.",
+    inputSchema: WriteFileInputSchema,
+    /**
+     * Check if this write operation needs directory access approval.
+     * Returns custom approval request if the file is outside allowed paths.
+     */
+    getApprovalOverride: (args) => {
+      const { file_path } = args;
+      if (!file_path) return null;
+      const isAllowed = fileSystemService.isPathWithinConfigAllowed(file_path);
+      if (isAllowed) {
+        return null;
+      }
+      if (directoryApproval?.isSessionApproved(file_path)) {
+        return null;
+      }
+      const absolutePath = path.resolve(file_path);
+      const parentDir = path.dirname(absolutePath);
+      pendingApprovalParentDir = parentDir;
+      return {
+        type: import_core.ApprovalType.DIRECTORY_ACCESS,
+        metadata: {
+          path: absolutePath,
+          parentDir,
+          operation: "write",
+          toolName: "write_file"
+        }
+      };
+    },
+    /**
+     * Handle approved directory access - remember the directory for session
+     */
+    onApprovalGranted: (response) => {
+      if (!directoryApproval || !pendingApprovalParentDir) return;
+      const data = response.data;
+      const rememberDirectory = data?.rememberDirectory ?? false;
+      directoryApproval.addApproved(
+        pendingApprovalParentDir,
+        rememberDirectory ? "session" : "once"
+      );
+      pendingApprovalParentDir = void 0;
+    },
+    /**
+     * Generate preview for approval UI - shows diff or file creation info
+     */
+    generatePreview: async (input, _context) => {
+      const { file_path, content } = input;
+      try {
+        const originalFile = await fileSystemService.readFile(file_path);
+        const originalContent = originalFile.content;
+        return generateDiffPreview(file_path, originalContent, content);
+      } catch (error) {
+        if (error instanceof import_core.DextoRuntimeError && error.code === import_error_codes.FileSystemErrorCode.FILE_NOT_FOUND) {
+          const lineCount = content.split("\n").length;
+          const preview = {
+            type: "file",
+            path: file_path,
+            operation: "create",
+            size: content.length,
+            lineCount,
+            content
+            // Include content for approval preview
+          };
+          return preview;
+        }
+        throw error;
+      }
+    },
+    execute: async (input, _context) => {
+      const { file_path, content, create_dirs, encoding } = input;
+      let originalContent = null;
+      try {
+        const originalFile = await fileSystemService.readFile(file_path);
+        originalContent = originalFile.content;
+      } catch (error) {
+        if (error instanceof import_core.DextoRuntimeError && error.code === import_error_codes.FileSystemErrorCode.FILE_NOT_FOUND) {
+          originalContent = null;
+        } else {
+          throw error;
+        }
+      }
+      const result = await fileSystemService.writeFile(file_path, content, {
+        createDirs: create_dirs,
+        encoding,
+        backup: true
+        // Always create backup for internal tools
+      });
+      let _display;
+      if (originalContent === null) {
+        const lineCount = content.split("\n").length;
+        _display = {
+          type: "file",
+          path: file_path,
+          operation: "create",
+          size: result.bytesWritten,
+          lineCount
+        };
+      } else {
+        _display = generateDiffPreview(file_path, originalContent, content);
+      }
+      return {
+        success: result.success,
+        path: result.path,
+        bytes_written: result.bytesWritten,
+        ...result.backupPath && { backup_path: result.backupPath },
+        _display
+      };
+    }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createWriteFileTool
+});

package/dist/write-file-tool.d.cts

@@ -0,0 +1,17 @@
+import { InternalTool } from '@dexto/core';
+import { FileToolOptions } from './file-tool-types.cjs';
+import './filesystem-service.cjs';
+import './types.cjs';
+
+/**
+ * Write File Tool
+ *
+ * Internal tool for writing content to files (requires approval)
+ */
+
+/**
+ * Create the write_file internal tool with directory approval support
+ */
+declare function createWriteFileTool(options: FileToolOptions): InternalTool;
+
+export { createWriteFileTool };

package/dist/write-file-tool.d.ts

@@ -0,0 +1,17 @@
+import { InternalTool } from '@dexto/core';
+import { FileToolOptions } from './file-tool-types.js';
+import './filesystem-service.js';
+import './types.js';
+
+/**
+ * Write File Tool
+ *
+ * Internal tool for writing content to files (requires approval)
+ */
+
+/**
+ * Create the write_file internal tool with directory approval support
+ */
+declare function createWriteFileTool(options: FileToolOptions): InternalTool;
+
+export { createWriteFileTool };

package/dist/write-file-tool.js

@@ -0,0 +1,143 @@
+import * as path from "node:path";
+import { z } from "zod";
+import { createPatch } from "diff";
+import { DextoRuntimeError, ApprovalType } from "@dexto/core";
+import { FileSystemErrorCode } from "./error-codes.js";
+const WriteFileInputSchema = z.object({
+  file_path: z.string().describe("Absolute path where the file should be written"),
+  content: z.string().describe("Content to write to the file"),
+  create_dirs: z.boolean().optional().default(false).describe("Create parent directories if they don't exist (default: false)"),
+  encoding: z.enum(["utf-8", "ascii", "latin1", "utf16le"]).optional().default("utf-8").describe("File encoding (default: utf-8)")
+}).strict();
+function generateDiffPreview(filePath, originalContent, newContent) {
+  const unified = createPatch(filePath, originalContent, newContent, "before", "after", {
+    context: 3
+  });
+  const additions = (unified.match(/^\+[^+]/gm) || []).length;
+  const deletions = (unified.match(/^-[^-]/gm) || []).length;
+  return {
+    type: "diff",
+    unified,
+    filename: filePath,
+    additions,
+    deletions
+  };
+}
+function createWriteFileTool(options) {
+  const { fileSystemService, directoryApproval } = options;
+  let pendingApprovalParentDir;
+  return {
+    id: "write_file",
+    description: "Write content to a file. Creates a new file or overwrites existing file. Automatically creates backup of existing files before overwriting. Use create_dirs to create parent directories. Requires approval for all write operations. Returns success status, path, bytes written, and backup path if applicable.",
+    inputSchema: WriteFileInputSchema,
+    /**
+     * Check if this write operation needs directory access approval.
+     * Returns custom approval request if the file is outside allowed paths.
+     */
+    getApprovalOverride: (args) => {
+      const { file_path } = args;
+      if (!file_path) return null;
+      const isAllowed = fileSystemService.isPathWithinConfigAllowed(file_path);
+      if (isAllowed) {
+        return null;
+      }
+      if (directoryApproval?.isSessionApproved(file_path)) {
+        return null;
+      }
+      const absolutePath = path.resolve(file_path);
+      const parentDir = path.dirname(absolutePath);
+      pendingApprovalParentDir = parentDir;
+      return {
+        type: ApprovalType.DIRECTORY_ACCESS,
+        metadata: {
+          path: absolutePath,
+          parentDir,
+          operation: "write",
+          toolName: "write_file"
+        }
+      };
+    },
+    /**
+     * Handle approved directory access - remember the directory for session
+     */
+    onApprovalGranted: (response) => {
+      if (!directoryApproval || !pendingApprovalParentDir) return;
+      const data = response.data;
+      const rememberDirectory = data?.rememberDirectory ?? false;
+      directoryApproval.addApproved(
+        pendingApprovalParentDir,
+        rememberDirectory ? "session" : "once"
+      );
+      pendingApprovalParentDir = void 0;
+    },
+    /**
+     * Generate preview for approval UI - shows diff or file creation info
+     */
+    generatePreview: async (input, _context) => {
+      const { file_path, content } = input;
+      try {
+        const originalFile = await fileSystemService.readFile(file_path);
+        const originalContent = originalFile.content;
+        return generateDiffPreview(file_path, originalContent, content);
+      } catch (error) {
+        if (error instanceof DextoRuntimeError && error.code === FileSystemErrorCode.FILE_NOT_FOUND) {
+          const lineCount = content.split("\n").length;
+          const preview = {
+            type: "file",
+            path: file_path,
+            operation: "create",
+            size: content.length,
+            lineCount,
+            content
+            // Include content for approval preview
+          };
+          return preview;
+        }
+        throw error;
+      }
+    },
+    execute: async (input, _context) => {
+      const { file_path, content, create_dirs, encoding } = input;
+      let originalContent = null;
+      try {
+        const originalFile = await fileSystemService.readFile(file_path);
+        originalContent = originalFile.content;
+      } catch (error) {
+        if (error instanceof DextoRuntimeError && error.code === FileSystemErrorCode.FILE_NOT_FOUND) {
+          originalContent = null;
+        } else {
+          throw error;
+        }
+      }
+      const result = await fileSystemService.writeFile(file_path, content, {
+        createDirs: create_dirs,
+        encoding,
+        backup: true
+        // Always create backup for internal tools
+      });
+      let _display;
+      if (originalContent === null) {
+        const lineCount = content.split("\n").length;
+        _display = {
+          type: "file",
+          path: file_path,
+          operation: "create",
+          size: result.bytesWritten,
+          lineCount
+        };
+      } else {
+        _display = generateDiffPreview(file_path, originalContent, content);
+      }
+      return {
+        success: result.success,
+        path: result.path,
+        bytes_written: result.bytesWritten,
+        ...result.backupPath && { backup_path: result.backupPath },
+        _display
+      };
+    }
+  };
+}
+export {
+  createWriteFileTool
+};

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@dexto/tools-filesystem",
+  "version": "1.5.0",
+  "description": "FileSystem tools provider for Dexto agents",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "keywords": [
+    "dexto",
+    "tools",
+    "filesystem",
+    "file-operations"
+  ],
+  "dependencies": {
+    "diff": "^7.0.0",
+    "glob": "^11.1.0",
+    "safe-regex": "^2.1.1",
+    "zod": "^3.25.0",
+    "@dexto/core": "1.5.0"
+  },
+  "devDependencies": {
+    "@types/diff": "^5.2.3",
+    "@types/safe-regex": "^1.1.6",
+    "tsup": "^8.0.0",
+    "typescript": "^5.3.3"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  }
+}