@dexto/tools-filesystem 1.5.0

package/dist/path-validator.test.js

@@ -0,0 +1,443 @@
+import { describe, it, expect, beforeEach, vi } from "vitest";
+import { PathValidator } from "./path-validator.js";
+const createMockLogger = () => ({
+  debug: vi.fn(),
+  info: vi.fn(),
+  warn: vi.fn(),
+  error: vi.fn(),
+  createChild: vi.fn().mockReturnThis()
+});
+describe("PathValidator", () => {
+  let mockLogger;
+  beforeEach(() => {
+    mockLogger = createMockLogger();
+    vi.clearAllMocks();
+  });
+  describe("validatePath", () => {
+    describe("Empty and Invalid Paths", () => {
+      it("should reject empty path", () => {
+        const validator = new PathValidator(
+          {
+            allowedPaths: ["/home/user/project"],
+            blockedPaths: [],
+            blockedExtensions: [],
+            maxFileSize: 10 * 1024 * 1024,
+            enableBackups: false,
+            backupRetentionDays: 7,
+            workingDirectory: "/home/user/project"
+          },
+          mockLogger
+        );
+        const result = validator.validatePath("");
+        expect(result.isValid).toBe(false);
+        expect(result.error).toBe("Path cannot be empty");
+      });
+      it("should reject whitespace-only path", () => {
+        const validator = new PathValidator(
+          {
+            allowedPaths: ["/home/user/project"],
+            blockedPaths: [],
+            blockedExtensions: [],
+            maxFileSize: 10 * 1024 * 1024,
+            enableBackups: false,
+            backupRetentionDays: 7,
+            workingDirectory: "/home/user/project"
+          },
+          mockLogger
+        );
+        const result = validator.validatePath("   ");
+        expect(result.isValid).toBe(false);
+        expect(result.error).toBe("Path cannot be empty");
+      });
+    });
+    describe("Allowed Paths", () => {
+      it("should allow paths within allowed directories", () => {
+        const validator = new PathValidator(
+          {
+            allowedPaths: ["/home/user/project"],
+            blockedPaths: [],
+            blockedExtensions: [],
+            maxFileSize: 10 * 1024 * 1024,
+            enableBackups: false,
+            backupRetentionDays: 7,
+            workingDirectory: "/home/user/project"
+          },
+          mockLogger
+        );
+        const result = validator.validatePath("/home/user/project/src/file.ts");
+        expect(result.isValid).toBe(true);
+        expect(result.normalizedPath).toBeDefined();
+      });
+      it("should allow relative paths within working directory", () => {
+        const validator = new PathValidator(
+          {
+            allowedPaths: ["/home/user/project"],
+            blockedPaths: [],
+            blockedExtensions: [],
+            maxFileSize: 10 * 1024 * 1024,
+            enableBackups: false,
+            backupRetentionDays: 7,
+            workingDirectory: "/home/user/project"
+          },
+          mockLogger
+        );
+        const result = validator.validatePath("src/file.ts");
+        expect(result.isValid).toBe(true);
+      });
+      it("should reject paths outside allowed directories", () => {
+        const validator = new PathValidator(
+          {
+            allowedPaths: ["/home/user/project"],
+            blockedPaths: [],
+            blockedExtensions: [],
+            maxFileSize: 10 * 1024 * 1024,
+            enableBackups: false,
+            backupRetentionDays: 7,
+            workingDirectory: "/home/user/project"
+          },
+          mockLogger
+        );
+        const result = validator.validatePath("/external/project/file.ts");
+        expect(result.isValid).toBe(false);
+        expect(result.error).toContain("not within allowed paths");
+      });
+      it("should allow all paths when allowedPaths is empty", () => {
+        const validator = new PathValidator(
+          {
+            allowedPaths: [],
+            blockedPaths: [],
+            blockedExtensions: [],
+            maxFileSize: 10 * 1024 * 1024,
+            enableBackups: false,
+            backupRetentionDays: 7,
+            workingDirectory: "/home/user/project"
+          },
+          mockLogger
+        );
+        const result = validator.validatePath("/anywhere/file.ts");
+        expect(result.isValid).toBe(true);
+      });
+    });
+    describe("Path Traversal Detection", () => {
+      it("should reject path traversal attempts", () => {
+        const validator = new PathValidator(
+          {
+            allowedPaths: ["/home/user/project"],
+            blockedPaths: [],
+            blockedExtensions: [],
+            maxFileSize: 10 * 1024 * 1024,
+            enableBackups: false,
+            backupRetentionDays: 7,
+            workingDirectory: "/home/user/project"
+          },
+          mockLogger
+        );
+        const result = validator.validatePath("/home/user/project/../../../etc/passwd");
+        expect(result.isValid).toBe(false);
+        expect(result.error).toBe("Path traversal detected");
+      });
+    });
+    describe("Blocked Paths", () => {
+      it("should reject paths in blocked directories", () => {
+        const validator = new PathValidator(
+          {
+            allowedPaths: ["/home/user/project"],
+            blockedPaths: [".git", "node_modules"],
+            blockedExtensions: [],
+            maxFileSize: 10 * 1024 * 1024,
+            enableBackups: false,
+            backupRetentionDays: 7,
+            workingDirectory: "/home/user/project"
+          },
+          mockLogger
+        );
+        const result = validator.validatePath("/home/user/project/.git/config");
+        expect(result.isValid).toBe(false);
+        expect(result.error).toContain("blocked");
+      });
+      it("should reject paths in node_modules", () => {
+        const validator = new PathValidator(
+          {
+            allowedPaths: ["/home/user/project"],
+            blockedPaths: ["node_modules"],
+            blockedExtensions: [],
+            maxFileSize: 10 * 1024 * 1024,
+            enableBackups: false,
+            backupRetentionDays: 7,
+            workingDirectory: "/home/user/project"
+          },
+          mockLogger
+        );
+        const result = validator.validatePath(
+          "/home/user/project/node_modules/lodash/index.js"
+        );
+        expect(result.isValid).toBe(false);
+        expect(result.error).toContain("blocked");
+      });
+    });
+    describe("Blocked Extensions", () => {
+      it("should reject files with blocked extensions", () => {
+        const validator = new PathValidator(
+          {
+            allowedPaths: ["/home/user/project"],
+            blockedPaths: [],
+            blockedExtensions: [".exe", ".dll"],
+            maxFileSize: 10 * 1024 * 1024,
+            enableBackups: false,
+            backupRetentionDays: 7,
+            workingDirectory: "/home/user/project"
+          },
+          mockLogger
+        );
+        const result = validator.validatePath("/home/user/project/malware.exe");
+        expect(result.isValid).toBe(false);
+        expect(result.error).toContain(".exe is not allowed");
+      });
+      it("should handle extensions without leading dot", () => {
+        const validator = new PathValidator(
+          {
+            allowedPaths: ["/home/user/project"],
+            blockedPaths: [],
+            blockedExtensions: ["exe", "dll"],
+            // No leading dot
+            maxFileSize: 10 * 1024 * 1024,
+            enableBackups: false,
+            backupRetentionDays: 7,
+            workingDirectory: "/home/user/project"
+          },
+          mockLogger
+        );
+        const result = validator.validatePath("/home/user/project/file.exe");
+        expect(result.isValid).toBe(false);
+      });
+      it("should be case-insensitive for extensions", () => {
+        const validator = new PathValidator(
+          {
+            allowedPaths: ["/home/user/project"],
+            blockedPaths: [],
+            blockedExtensions: [".exe"],
+            maxFileSize: 10 * 1024 * 1024,
+            enableBackups: false,
+            backupRetentionDays: 7,
+            workingDirectory: "/home/user/project"
+          },
+          mockLogger
+        );
+        const result = validator.validatePath("/home/user/project/file.EXE");
+        expect(result.isValid).toBe(false);
+      });
+    });
+    describe("Directory Approval Checker Integration", () => {
+      it("should consult approval checker for external paths", () => {
+        const validator = new PathValidator(
+          {
+            allowedPaths: ["/home/user/project"],
+            blockedPaths: [],
+            blockedExtensions: [],
+            maxFileSize: 10 * 1024 * 1024,
+            enableBackups: false,
+            backupRetentionDays: 7,
+            workingDirectory: "/home/user/project"
+          },
+          mockLogger
+        );
+        let result = validator.validatePath("/external/project/file.ts");
+        expect(result.isValid).toBe(false);
+        const approvalChecker = (filePath) => {
+          return filePath.startsWith("/external/project");
+        };
+        validator.setDirectoryApprovalChecker(approvalChecker);
+        result = validator.validatePath("/external/project/file.ts");
+        expect(result.isValid).toBe(true);
+      });
+      it("should not use approval checker for config-allowed paths", () => {
+        const approvalChecker = vi.fn().mockReturnValue(false);
+        const validator = new PathValidator(
+          {
+            allowedPaths: ["/home/user/project"],
+            blockedPaths: [],
+            blockedExtensions: [],
+            maxFileSize: 10 * 1024 * 1024,
+            enableBackups: false,
+            backupRetentionDays: 7,
+            workingDirectory: "/home/user/project"
+          },
+          mockLogger
+        );
+        validator.setDirectoryApprovalChecker(approvalChecker);
+        const result = validator.validatePath("/home/user/project/src/file.ts");
+        expect(result.isValid).toBe(true);
+        expect(approvalChecker).not.toHaveBeenCalled();
+      });
+    });
+  });
+  describe("isPathWithinAllowed", () => {
+    it("should return true for paths within config-allowed directories", () => {
+      const validator = new PathValidator(
+        {
+          allowedPaths: ["/home/user/project"],
+          blockedPaths: [],
+          blockedExtensions: [],
+          maxFileSize: 10 * 1024 * 1024,
+          enableBackups: false,
+          backupRetentionDays: 7,
+          workingDirectory: "/home/user/project"
+        },
+        mockLogger
+      );
+      expect(validator.isPathWithinAllowed("/home/user/project/src/file.ts")).toBe(true);
+      expect(validator.isPathWithinAllowed("/home/user/project/deep/nested/file.ts")).toBe(
+        true
+      );
+    });
+    it("should return false for paths outside config-allowed directories", () => {
+      const validator = new PathValidator(
+        {
+          allowedPaths: ["/home/user/project"],
+          blockedPaths: [],
+          blockedExtensions: [],
+          maxFileSize: 10 * 1024 * 1024,
+          enableBackups: false,
+          backupRetentionDays: 7,
+          workingDirectory: "/home/user/project"
+        },
+        mockLogger
+      );
+      expect(validator.isPathWithinAllowed("/external/project/file.ts")).toBe(false);
+      expect(validator.isPathWithinAllowed("/home/user/other/file.ts")).toBe(false);
+    });
+    it("should NOT consult approval checker (used for prompting decisions)", () => {
+      const approvalChecker = vi.fn().mockReturnValue(true);
+      const validator = new PathValidator(
+        {
+          allowedPaths: ["/home/user/project"],
+          blockedPaths: [],
+          blockedExtensions: [],
+          maxFileSize: 10 * 1024 * 1024,
+          enableBackups: false,
+          backupRetentionDays: 7,
+          workingDirectory: "/home/user/project"
+        },
+        mockLogger
+      );
+      validator.setDirectoryApprovalChecker(approvalChecker);
+      expect(validator.isPathWithinAllowed("/external/project/file.ts")).toBe(false);
+      expect(approvalChecker).not.toHaveBeenCalled();
+    });
+    it("should return false for empty path", () => {
+      const validator = new PathValidator(
+        {
+          allowedPaths: ["/home/user/project"],
+          blockedPaths: [],
+          blockedExtensions: [],
+          maxFileSize: 10 * 1024 * 1024,
+          enableBackups: false,
+          backupRetentionDays: 7,
+          workingDirectory: "/home/user/project"
+        },
+        mockLogger
+      );
+      expect(validator.isPathWithinAllowed("")).toBe(false);
+      expect(validator.isPathWithinAllowed("   ")).toBe(false);
+    });
+    it("should return true when allowedPaths is empty (all paths allowed)", () => {
+      const validator = new PathValidator(
+        {
+          allowedPaths: [],
+          blockedPaths: [],
+          blockedExtensions: [],
+          maxFileSize: 10 * 1024 * 1024,
+          enableBackups: false,
+          backupRetentionDays: 7,
+          workingDirectory: "/home/user/project"
+        },
+        mockLogger
+      );
+      expect(validator.isPathWithinAllowed("/anywhere/file.ts")).toBe(true);
+    });
+  });
+  describe("Path Containment (Parent Directory Coverage)", () => {
+    it("should recognize that approving parent covers child paths", () => {
+      const validator = new PathValidator(
+        {
+          allowedPaths: ["/external/sub"],
+          blockedPaths: [],
+          blockedExtensions: [],
+          maxFileSize: 10 * 1024 * 1024,
+          enableBackups: false,
+          backupRetentionDays: 7,
+          workingDirectory: "/home/user/project"
+        },
+        mockLogger
+      );
+      expect(validator.isPathWithinAllowed("/external/sub/deep/nested/file.ts")).toBe(true);
+    });
+    it("should not allow sibling directories", () => {
+      const validator = new PathValidator(
+        {
+          allowedPaths: ["/external/sub"],
+          blockedPaths: [],
+          blockedExtensions: [],
+          maxFileSize: 10 * 1024 * 1024,
+          enableBackups: false,
+          backupRetentionDays: 7,
+          workingDirectory: "/home/user/project"
+        },
+        mockLogger
+      );
+      expect(validator.isPathWithinAllowed("/external/other/file.ts")).toBe(false);
+    });
+    it("should not allow parent directories when child is approved", () => {
+      const validator = new PathValidator(
+        {
+          allowedPaths: ["/external/sub/deep"],
+          blockedPaths: [],
+          blockedExtensions: [],
+          maxFileSize: 10 * 1024 * 1024,
+          enableBackups: false,
+          backupRetentionDays: 7,
+          workingDirectory: "/home/user/project"
+        },
+        mockLogger
+      );
+      expect(validator.isPathWithinAllowed("/external/sub/file.ts")).toBe(false);
+    });
+  });
+  describe("getAllowedPaths and getBlockedPaths", () => {
+    it("should return normalized allowed paths", () => {
+      const validator = new PathValidator(
+        {
+          allowedPaths: [".", "./src"],
+          blockedPaths: [],
+          blockedExtensions: [],
+          maxFileSize: 10 * 1024 * 1024,
+          enableBackups: false,
+          backupRetentionDays: 7,
+          workingDirectory: "/home/user/project"
+        },
+        mockLogger
+      );
+      const allowedPaths = validator.getAllowedPaths();
+      expect(allowedPaths).toHaveLength(2);
+      expect(allowedPaths[0]).toBe("/home/user/project");
+      expect(allowedPaths[1]).toBe("/home/user/project/src");
+    });
+    it("should return blocked paths", () => {
+      const validator = new PathValidator(
+        {
+          allowedPaths: ["/home/user/project"],
+          blockedPaths: [".git", "node_modules"],
+          blockedExtensions: [],
+          maxFileSize: 10 * 1024 * 1024,
+          enableBackups: false,
+          backupRetentionDays: 7,
+          workingDirectory: "/home/user/project"
+        },
+        mockLogger
+      );
+      const blockedPaths = validator.getBlockedPaths();
+      expect(blockedPaths).toContain(".git");
+      expect(blockedPaths).toContain("node_modules");
+    });
+  });
+});

package/dist/read-file-tool.cjs

@@ -0,0 +1,117 @@
+"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 read_file_tool_exports = {};
+__export(read_file_tool_exports, {
+  createReadFileTool: () => createReadFileTool
+});
+module.exports = __toCommonJS(read_file_tool_exports);
+var path = __toESM(require("node:path"), 1);
+var import_zod = require("zod");
+var import_core = require("@dexto/core");
+const ReadFileInputSchema = import_zod.z.object({
+  file_path: import_zod.z.string().describe("Absolute path to the file to read"),
+  limit: import_zod.z.number().int().positive().optional().describe("Maximum number of lines to read (optional)"),
+  offset: import_zod.z.number().int().min(1).optional().describe("Starting line number (1-based, optional)")
+}).strict();
+function createReadFileTool(options) {
+  const { fileSystemService, directoryApproval } = options;
+  let pendingApprovalParentDir;
+  return {
+    id: "read_file",
+    description: "Read the contents of a file with optional pagination. Returns file content, line count, encoding, and whether the output was truncated. Use limit and offset parameters for large files to read specific sections. This tool is for reading files within allowed paths only.",
+    inputSchema: ReadFileInputSchema,
+    /**
+     * Check if this read 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: "read",
+          toolName: "read_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;
+    },
+    execute: async (input, _context) => {
+      const { file_path, limit, offset } = input;
+      const result = await fileSystemService.readFile(file_path, {
+        limit,
+        offset
+      });
+      const _display = {
+        type: "file",
+        path: file_path,
+        operation: "read",
+        size: result.size,
+        lineCount: result.lines
+      };
+      return {
+        content: result.content,
+        lines: result.lines,
+        encoding: result.encoding,
+        truncated: result.truncated,
+        size: result.size,
+        ...result.mimeType && { mimeType: result.mimeType },
+        _display
+      };
+    }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createReadFileTool
+});

package/dist/read-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';
+
+/**
+ * Read File Tool
+ *
+ * Internal tool for reading file contents with size limits and pagination
+ */
+
+/**
+ * Create the read_file internal tool with directory approval support
+ */
+declare function createReadFileTool(options: FileToolOptions): InternalTool;
+
+export { createReadFileTool };

package/dist/read-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';
+
+/**
+ * Read File Tool
+ *
+ * Internal tool for reading file contents with size limits and pagination
+ */
+
+/**
+ * Create the read_file internal tool with directory approval support
+ */
+declare function createReadFileTool(options: FileToolOptions): InternalTool;
+
+export { createReadFileTool };

package/dist/read-file-tool.js

@@ -0,0 +1,83 @@
+import * as path from "node:path";
+import { z } from "zod";
+import { ApprovalType } from "@dexto/core";
+const ReadFileInputSchema = z.object({
+  file_path: z.string().describe("Absolute path to the file to read"),
+  limit: z.number().int().positive().optional().describe("Maximum number of lines to read (optional)"),
+  offset: z.number().int().min(1).optional().describe("Starting line number (1-based, optional)")
+}).strict();
+function createReadFileTool(options) {
+  const { fileSystemService, directoryApproval } = options;
+  let pendingApprovalParentDir;
+  return {
+    id: "read_file",
+    description: "Read the contents of a file with optional pagination. Returns file content, line count, encoding, and whether the output was truncated. Use limit and offset parameters for large files to read specific sections. This tool is for reading files within allowed paths only.",
+    inputSchema: ReadFileInputSchema,
+    /**
+     * Check if this read 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: "read",
+          toolName: "read_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;
+    },
+    execute: async (input, _context) => {
+      const { file_path, limit, offset } = input;
+      const result = await fileSystemService.readFile(file_path, {
+        limit,
+        offset
+      });
+      const _display = {
+        type: "file",
+        path: file_path,
+        operation: "read",
+        size: result.size,
+        lineCount: result.lines
+      };
+      return {
+        content: result.content,
+        lines: result.lines,
+        encoding: result.encoding,
+        truncated: result.truncated,
+        size: result.size,
+        ...result.mimeType && { mimeType: result.mimeType },
+        _display
+      };
+    }
+  };
+}
+export {
+  createReadFileTool
+};