@dexto/tools-filesystem 1.5.0

package/dist/directory-approval.integration.test.js

@@ -0,0 +1,444 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import * as path from "node:path";
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import { createReadFileTool } from "./read-file-tool.js";
+import { createWriteFileTool } from "./write-file-tool.js";
+import { createEditFileTool } from "./edit-file-tool.js";
+import { FileSystemService } from "./filesystem-service.js";
+import { ApprovalType, ApprovalStatus } from "@dexto/core";
+const createMockLogger = () => ({
+  debug: vi.fn(),
+  info: vi.fn(),
+  warn: vi.fn(),
+  error: vi.fn(),
+  createChild: vi.fn().mockReturnThis()
+});
+describe("Directory Approval Integration Tests", () => {
+  let mockLogger;
+  let tempDir;
+  let fileSystemService;
+  let directoryApproval;
+  let isSessionApprovedMock;
+  let addApprovedMock;
+  beforeEach(async () => {
+    mockLogger = createMockLogger();
+    const rawTempDir = await fs.mkdtemp(path.join(os.tmpdir(), "dexto-fs-test-"));
+    tempDir = await fs.realpath(rawTempDir);
+    fileSystemService = new FileSystemService(
+      {
+        allowedPaths: [tempDir],
+        blockedPaths: [],
+        blockedExtensions: [],
+        maxFileSize: 10 * 1024 * 1024,
+        workingDirectory: tempDir,
+        enableBackups: false,
+        backupRetentionDays: 7
+      },
+      mockLogger
+    );
+    await fileSystemService.initialize();
+    isSessionApprovedMock = vi.fn().mockReturnValue(false);
+    addApprovedMock = vi.fn();
+    directoryApproval = {
+      isSessionApproved: isSessionApprovedMock,
+      addApproved: addApprovedMock
+    };
+    vi.clearAllMocks();
+  });
+  afterEach(async () => {
+    try {
+      await fs.rm(tempDir, { recursive: true, force: true });
+    } catch {
+    }
+  });
+  describe("Read File Tool", () => {
+    describe("getApprovalOverride", () => {
+      it("should return null for paths within working directory (no prompt needed)", async () => {
+        const tool = createReadFileTool({
+          fileSystemService,
+          directoryApproval
+        });
+        const testFile = path.join(tempDir, "test.txt");
+        await fs.writeFile(testFile, "test content");
+        const override = tool.getApprovalOverride?.({ file_path: testFile });
+        expect(override).toBeNull();
+      });
+      it("should return directory access approval for external paths", async () => {
+        const tool = createReadFileTool({
+          fileSystemService,
+          directoryApproval
+        });
+        const externalPath = "/external/project/file.ts";
+        const override = tool.getApprovalOverride?.({ file_path: externalPath });
+        expect(override).not.toBeNull();
+        expect(override?.type).toBe(ApprovalType.DIRECTORY_ACCESS);
+        const metadata = override?.metadata;
+        expect(metadata?.path).toBe(path.resolve(externalPath));
+        expect(metadata?.parentDir).toBe(path.dirname(path.resolve(externalPath)));
+        expect(metadata?.operation).toBe("read");
+        expect(metadata?.toolName).toBe("read_file");
+      });
+      it("should return null when external path is session-approved", async () => {
+        isSessionApprovedMock.mockReturnValue(true);
+        const tool = createReadFileTool({
+          fileSystemService,
+          directoryApproval
+        });
+        const externalPath = "/external/project/file.ts";
+        const override = tool.getApprovalOverride?.({ file_path: externalPath });
+        expect(override).toBeNull();
+        expect(isSessionApprovedMock).toHaveBeenCalledWith(externalPath);
+      });
+      it("should return null when file_path is missing", async () => {
+        const tool = createReadFileTool({
+          fileSystemService,
+          directoryApproval
+        });
+        const override = tool.getApprovalOverride?.({});
+        expect(override).toBeNull();
+      });
+    });
+    describe("onApprovalGranted", () => {
+      it("should add directory as session-approved when rememberDirectory is true", async () => {
+        const tool = createReadFileTool({
+          fileSystemService,
+          directoryApproval
+        });
+        const externalPath = "/external/project/file.ts";
+        tool.getApprovalOverride?.({ file_path: externalPath });
+        tool.onApprovalGranted?.({
+          approvalId: "test-approval",
+          status: ApprovalStatus.APPROVED,
+          data: { rememberDirectory: true }
+        });
+        expect(addApprovedMock).toHaveBeenCalledWith(
+          path.dirname(path.resolve(externalPath)),
+          "session"
+        );
+      });
+      it("should add directory as once-approved when rememberDirectory is false", async () => {
+        const tool = createReadFileTool({
+          fileSystemService,
+          directoryApproval
+        });
+        const externalPath = "/external/project/file.ts";
+        tool.getApprovalOverride?.({ file_path: externalPath });
+        tool.onApprovalGranted?.({
+          approvalId: "test-approval",
+          status: ApprovalStatus.APPROVED,
+          data: { rememberDirectory: false }
+        });
+        expect(addApprovedMock).toHaveBeenCalledWith(
+          path.dirname(path.resolve(externalPath)),
+          "once"
+        );
+      });
+      it("should default to once-approved when rememberDirectory is not specified", async () => {
+        const tool = createReadFileTool({
+          fileSystemService,
+          directoryApproval
+        });
+        const externalPath = "/external/project/file.ts";
+        tool.getApprovalOverride?.({ file_path: externalPath });
+        tool.onApprovalGranted?.({
+          approvalId: "test-approval",
+          status: ApprovalStatus.APPROVED,
+          data: {}
+        });
+        expect(addApprovedMock).toHaveBeenCalledWith(
+          path.dirname(path.resolve(externalPath)),
+          "once"
+        );
+      });
+      it("should not call addApproved when directoryApproval is not provided", async () => {
+        const tool = createReadFileTool({
+          fileSystemService,
+          directoryApproval: void 0
+        });
+        const externalPath = "/external/project/file.ts";
+        tool.getApprovalOverride?.({ file_path: externalPath });
+        tool.onApprovalGranted?.({
+          approvalId: "test-approval",
+          status: ApprovalStatus.APPROVED,
+          data: { rememberDirectory: true }
+        });
+        expect(addApprovedMock).not.toHaveBeenCalled();
+      });
+    });
+    describe("execute", () => {
+      it("should read file contents within working directory", async () => {
+        const tool = createReadFileTool({
+          fileSystemService,
+          directoryApproval
+        });
+        const testFile = path.join(tempDir, "readable.txt");
+        await fs.writeFile(testFile, "Hello, world!\nLine 2");
+        const result = await tool.execute({ file_path: testFile }, {});
+        expect(result.content).toBe("Hello, world!\nLine 2");
+        expect(result.lines).toBe(2);
+      });
+    });
+  });
+  describe("Write File Tool", () => {
+    describe("getApprovalOverride", () => {
+      it("should return null for paths within working directory", async () => {
+        const tool = createWriteFileTool({
+          fileSystemService,
+          directoryApproval
+        });
+        const testFile = path.join(tempDir, "new-file.txt");
+        const override = tool.getApprovalOverride?.({
+          file_path: testFile,
+          content: "test"
+        });
+        expect(override).toBeNull();
+      });
+      it("should return directory access approval for external paths", async () => {
+        const tool = createWriteFileTool({
+          fileSystemService,
+          directoryApproval
+        });
+        const externalPath = "/external/project/new.ts";
+        const override = tool.getApprovalOverride?.({
+          file_path: externalPath,
+          content: "test"
+        });
+        expect(override).not.toBeNull();
+        expect(override?.type).toBe(ApprovalType.DIRECTORY_ACCESS);
+        const metadata = override?.metadata;
+        expect(metadata?.operation).toBe("write");
+        expect(metadata?.toolName).toBe("write_file");
+      });
+      it("should return null when external path is session-approved", async () => {
+        isSessionApprovedMock.mockReturnValue(true);
+        const tool = createWriteFileTool({
+          fileSystemService,
+          directoryApproval
+        });
+        const externalPath = "/external/project/new.ts";
+        const override = tool.getApprovalOverride?.({
+          file_path: externalPath,
+          content: "test"
+        });
+        expect(override).toBeNull();
+      });
+    });
+    describe("onApprovalGranted", () => {
+      it("should add directory as session-approved when rememberDirectory is true", async () => {
+        const tool = createWriteFileTool({
+          fileSystemService,
+          directoryApproval
+        });
+        const externalPath = "/external/project/new.ts";
+        tool.getApprovalOverride?.({ file_path: externalPath, content: "test" });
+        tool.onApprovalGranted?.({
+          approvalId: "test-approval",
+          status: ApprovalStatus.APPROVED,
+          data: { rememberDirectory: true }
+        });
+        expect(addApprovedMock).toHaveBeenCalledWith(
+          path.dirname(path.resolve(externalPath)),
+          "session"
+        );
+      });
+    });
+  });
+  describe("Edit File Tool", () => {
+    describe("getApprovalOverride", () => {
+      it("should return null for paths within working directory", async () => {
+        const tool = createEditFileTool({
+          fileSystemService,
+          directoryApproval
+        });
+        const testFile = path.join(tempDir, "existing.txt");
+        const override = tool.getApprovalOverride?.({
+          file_path: testFile,
+          old_string: "old",
+          new_string: "new"
+        });
+        expect(override).toBeNull();
+      });
+      it("should return directory access approval for external paths", async () => {
+        const tool = createEditFileTool({
+          fileSystemService,
+          directoryApproval
+        });
+        const externalPath = "/external/project/existing.ts";
+        const override = tool.getApprovalOverride?.({
+          file_path: externalPath,
+          old_string: "old",
+          new_string: "new"
+        });
+        expect(override).not.toBeNull();
+        expect(override?.type).toBe(ApprovalType.DIRECTORY_ACCESS);
+        const metadata = override?.metadata;
+        expect(metadata?.operation).toBe("edit");
+        expect(metadata?.toolName).toBe("edit_file");
+      });
+      it("should return null when external path is session-approved", async () => {
+        isSessionApprovedMock.mockReturnValue(true);
+        const tool = createEditFileTool({
+          fileSystemService,
+          directoryApproval
+        });
+        const externalPath = "/external/project/existing.ts";
+        const override = tool.getApprovalOverride?.({
+          file_path: externalPath,
+          old_string: "old",
+          new_string: "new"
+        });
+        expect(override).toBeNull();
+      });
+    });
+  });
+  describe("Session vs Once Approval Scenarios", () => {
+    it("should not prompt for subsequent requests after session approval", async () => {
+      const tool = createReadFileTool({
+        fileSystemService,
+        directoryApproval
+      });
+      const externalPath1 = "/external/project/file1.ts";
+      const externalPath2 = "/external/project/file2.ts";
+      let override = tool.getApprovalOverride?.({ file_path: externalPath1 });
+      expect(override).not.toBeNull();
+      tool.onApprovalGranted?.({
+        approvalId: "approval-1",
+        status: ApprovalStatus.APPROVED,
+        data: { rememberDirectory: true }
+      });
+      expect(addApprovedMock).toHaveBeenCalledWith(
+        path.dirname(path.resolve(externalPath1)),
+        "session"
+      );
+      isSessionApprovedMock.mockReturnValue(true);
+      override = tool.getApprovalOverride?.({ file_path: externalPath2 });
+      expect(override).toBeNull();
+    });
+    it("should prompt for subsequent requests after once approval", async () => {
+      const tool = createReadFileTool({
+        fileSystemService,
+        directoryApproval
+      });
+      const externalPath1 = "/external/project/file1.ts";
+      const externalPath2 = "/external/project/file2.ts";
+      let override = tool.getApprovalOverride?.({ file_path: externalPath1 });
+      expect(override).not.toBeNull();
+      tool.onApprovalGranted?.({
+        approvalId: "approval-1",
+        status: ApprovalStatus.APPROVED,
+        data: { rememberDirectory: false }
+      });
+      expect(addApprovedMock).toHaveBeenCalledWith(
+        path.dirname(path.resolve(externalPath1)),
+        "once"
+      );
+      isSessionApprovedMock.mockReturnValue(false);
+      override = tool.getApprovalOverride?.({ file_path: externalPath2 });
+      expect(override).not.toBeNull();
+    });
+  });
+  describe("Path Containment Scenarios", () => {
+    it("should cover child paths when parent directory is session-approved", async () => {
+      const tool = createReadFileTool({
+        fileSystemService,
+        directoryApproval
+      });
+      isSessionApprovedMock.mockImplementation((filePath) => {
+        const normalizedPath = path.resolve(filePath);
+        const approvedDir = "/external/project";
+        return normalizedPath.startsWith(approvedDir + path.sep) || normalizedPath === approvedDir;
+      });
+      let override = tool.getApprovalOverride?.({ file_path: "/external/project/file.ts" });
+      expect(override).toBeNull();
+      override = tool.getApprovalOverride?.({
+        file_path: "/external/project/deep/nested/file.ts"
+      });
+      expect(override).toBeNull();
+    });
+    it("should NOT cover sibling directories", async () => {
+      const tool = createReadFileTool({
+        fileSystemService,
+        directoryApproval
+      });
+      isSessionApprovedMock.mockImplementation((filePath) => {
+        const normalizedPath = path.resolve(filePath);
+        const approvedDir = "/external/sub";
+        return normalizedPath.startsWith(approvedDir + path.sep) || normalizedPath === approvedDir;
+      });
+      let override = tool.getApprovalOverride?.({ file_path: "/external/sub/file.ts" });
+      expect(override).toBeNull();
+      override = tool.getApprovalOverride?.({ file_path: "/external/other/file.ts" });
+      expect(override).not.toBeNull();
+    });
+  });
+  describe("Different External Directories Scenarios", () => {
+    it("should require separate approval for different external directories", async () => {
+      const tool = createReadFileTool({
+        fileSystemService,
+        directoryApproval
+      });
+      const dir1Path = "/external/project1/file.ts";
+      const dir2Path = "/external/project2/file.ts";
+      const override1 = tool.getApprovalOverride?.({ file_path: dir1Path });
+      expect(override1).not.toBeNull();
+      const metadata1 = override1?.metadata;
+      expect(metadata1?.parentDir).toBe("/external/project1");
+      const override2 = tool.getApprovalOverride?.({ file_path: dir2Path });
+      expect(override2).not.toBeNull();
+      const metadata2 = override2?.metadata;
+      expect(metadata2?.parentDir).toBe("/external/project2");
+    });
+  });
+  describe("Mixed Operations Scenarios", () => {
+    it("should share directory approval across different file operations", async () => {
+      const readTool = createReadFileTool({ fileSystemService, directoryApproval });
+      const writeTool = createWriteFileTool({ fileSystemService, directoryApproval });
+      const editTool = createEditFileTool({ fileSystemService, directoryApproval });
+      const externalDir = "/external/project";
+      expect(
+        readTool.getApprovalOverride?.({ file_path: `${externalDir}/file1.ts` })
+      ).not.toBeNull();
+      expect(
+        writeTool.getApprovalOverride?.({
+          file_path: `${externalDir}/file2.ts`,
+          content: "test"
+        })
+      ).not.toBeNull();
+      expect(
+        editTool.getApprovalOverride?.({
+          file_path: `${externalDir}/file3.ts`,
+          old_string: "a",
+          new_string: "b"
+        })
+      ).not.toBeNull();
+      isSessionApprovedMock.mockReturnValue(true);
+      expect(
+        readTool.getApprovalOverride?.({ file_path: `${externalDir}/file1.ts` })
+      ).toBeNull();
+      expect(
+        writeTool.getApprovalOverride?.({
+          file_path: `${externalDir}/file2.ts`,
+          content: "test"
+        })
+      ).toBeNull();
+      expect(
+        editTool.getApprovalOverride?.({
+          file_path: `${externalDir}/file3.ts`,
+          old_string: "a",
+          new_string: "b"
+        })
+      ).toBeNull();
+    });
+  });
+  describe("Without Directory Approval Callbacks", () => {
+    it("should work without directory approval callbacks (all paths need normal tool confirmation)", async () => {
+      const tool = createReadFileTool({
+        fileSystemService,
+        directoryApproval: void 0
+      });
+      const override = tool.getApprovalOverride?.({ file_path: "/external/project/file.ts" });
+      expect(override).not.toBeNull();
+    });
+  });
+});

package/dist/edit-file-tool.cjs

@@ -0,0 +1,181 @@
+"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 edit_file_tool_exports = {};
+__export(edit_file_tool_exports, {
+  createEditFileTool: () => createEditFileTool
+});
+module.exports = __toCommonJS(edit_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_core2 = require("@dexto/core");
+var import_core3 = require("@dexto/core");
+var import_core4 = require("@dexto/core");
+const EditFileInputSchema = import_zod.z.object({
+  file_path: import_zod.z.string().describe("Absolute path to the file to edit"),
+  old_string: import_zod.z.string().describe("Text to replace (must be unique unless replace_all is true)"),
+  new_string: import_zod.z.string().describe("Replacement text"),
+  replace_all: import_zod.z.boolean().optional().default(false).describe("Replace all occurrences (default: false, requires unique match)")
+}).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 createEditFileTool(options) {
+  const { fileSystemService, directoryApproval } = options;
+  let pendingApprovalParentDir;
+  return {
+    id: "edit_file",
+    description: "Edit a file by replacing text. By default, old_string must be unique in the file (will error if found multiple times). Set replace_all=true to replace all occurrences. Automatically creates backup before editing. Requires approval. Returns success status, path, number of changes made, and backup path.",
+    inputSchema: EditFileInputSchema,
+    /**
+     * Check if this edit 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: "edit",
+          toolName: "edit_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 without modifying file
+     * Throws ToolError.validationFailed() for validation errors (file not found, string not found)
+     */
+    generatePreview: async (input, _context) => {
+      const { file_path, old_string, new_string, replace_all } = input;
+      try {
+        const originalFile = await fileSystemService.readFile(file_path);
+        const originalContent = originalFile.content;
+        if (!replace_all) {
+          const occurrences = originalContent.split(old_string).length - 1;
+          if (occurrences > 1) {
+            throw import_core2.ToolError.validationFailed(
+              "edit_file",
+              `String found ${occurrences} times in file. Set replace_all=true to replace all, or provide more context to make old_string unique.`,
+              { file_path, occurrences }
+            );
+          }
+        }
+        const newContent = replace_all ? originalContent.split(old_string).join(new_string) : originalContent.replace(old_string, new_string);
+        if (originalContent === newContent) {
+          throw import_core2.ToolError.validationFailed(
+            "edit_file",
+            `String not found in file: "${old_string.slice(0, 50)}${old_string.length > 50 ? "..." : ""}"`,
+            { file_path, old_string_preview: old_string.slice(0, 100) }
+          );
+        }
+        return generateDiffPreview(file_path, originalContent, newContent);
+      } catch (error) {
+        if (error instanceof import_core4.DextoRuntimeError && error.code === import_core3.ToolErrorCode.VALIDATION_FAILED) {
+          throw error;
+        }
+        if (error instanceof import_core4.DextoRuntimeError) {
+          throw import_core2.ToolError.validationFailed("edit_file", error.message, {
+            file_path,
+            originalErrorCode: error.code
+          });
+        }
+        return null;
+      }
+    },
+    execute: async (input, _context) => {
+      const { file_path, old_string, new_string, replace_all } = input;
+      const originalFile = await fileSystemService.readFile(file_path);
+      const originalContent = originalFile.content;
+      const result = await fileSystemService.editFile(
+        file_path,
+        {
+          oldString: old_string,
+          newString: new_string,
+          replaceAll: replace_all
+        },
+        {
+          backup: true
+          // Always create backup for internal tools
+        }
+      );
+      const newFile = await fileSystemService.readFile(file_path);
+      const newContent = newFile.content;
+      const _display = generateDiffPreview(file_path, originalContent, newContent);
+      return {
+        success: result.success,
+        path: result.path,
+        changes_count: result.changesCount,
+        ...result.backupPath && { backup_path: result.backupPath },
+        _display
+      };
+    }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createEditFileTool
+});

package/dist/edit-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';
+
+/**
+ * Edit File Tool
+ *
+ * Internal tool for editing files by replacing text (requires approval)
+ */
+
+/**
+ * Create the edit_file internal tool with directory approval support
+ */
+declare function createEditFileTool(options: FileToolOptions): InternalTool;
+
+export { createEditFileTool };

package/dist/edit-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';
+
+/**
+ * Edit File Tool
+ *
+ * Internal tool for editing files by replacing text (requires approval)
+ */
+
+/**
+ * Create the edit_file internal tool with directory approval support
+ */
+declare function createEditFileTool(options: FileToolOptions): InternalTool;
+
+export { createEditFileTool };