@dexto/tools-filesystem 1.5.0

package/dist/errors.d.cts

@@ -0,0 +1,112 @@
+import { DextoRuntimeError } from '@dexto/core';
+
+/**
+ * FileSystem Service Errors
+ *
+ * Error classes for file system operations
+ */
+
+interface FileSystemErrorContext {
+    path?: string;
+    pattern?: string;
+    size?: number;
+    maxSize?: number;
+    encoding?: string;
+    operation?: string;
+}
+/**
+ * Factory class for creating FileSystem-related errors
+ */
+declare class FileSystemError {
+    private constructor();
+    /**
+     * File not found error
+     */
+    static fileNotFound(path: string): DextoRuntimeError;
+    /**
+     * Directory not found error
+     */
+    static directoryNotFound(path: string): DextoRuntimeError;
+    /**
+     * Permission denied error
+     */
+    static permissionDenied(path: string, operation: string): DextoRuntimeError;
+    /**
+     * Path not allowed error
+     */
+    static pathNotAllowed(path: string, allowedPaths: string[]): DextoRuntimeError;
+    /**
+     * Path blocked error
+     */
+    static pathBlocked(path: string, reason: string): DextoRuntimeError;
+    /**
+     * Invalid path error
+     */
+    static invalidPath(path: string, reason: string): DextoRuntimeError;
+    /**
+     * Path traversal detected
+     */
+    static pathTraversal(path: string): DextoRuntimeError;
+    /**
+     * Invalid file extension error
+     */
+    static invalidExtension(path: string, blockedExtensions: string[]): DextoRuntimeError;
+    /**
+     * File too large error
+     */
+    static fileTooLarge(path: string, size: number, maxSize: number): DextoRuntimeError;
+    /**
+     * Too many results error
+     */
+    static tooManyResults(operation: string, count: number, maxResults: number): DextoRuntimeError;
+    /**
+     * Read operation failed
+     */
+    static readFailed(path: string, cause: string): DextoRuntimeError;
+    /**
+     * Write operation failed
+     */
+    static writeFailed(path: string, cause: string): DextoRuntimeError;
+    /**
+     * Backup creation failed
+     */
+    static backupFailed(path: string, cause: string): DextoRuntimeError;
+    /**
+     * Edit operation failed
+     */
+    static editFailed(path: string, cause: string): DextoRuntimeError;
+    /**
+     * String not unique error
+     */
+    static stringNotUnique(path: string, searchString: string, occurrences: number): DextoRuntimeError;
+    /**
+     * String not found error
+     */
+    static stringNotFound(path: string, searchString: string): DextoRuntimeError;
+    /**
+     * Glob operation failed
+     */
+    static globFailed(pattern: string, cause: string): DextoRuntimeError;
+    /**
+     * Search operation failed
+     */
+    static searchFailed(pattern: string, cause: string): DextoRuntimeError;
+    /**
+     * Invalid pattern error
+     */
+    static invalidPattern(pattern: string, cause: string): DextoRuntimeError;
+    /**
+     * Regex timeout error
+     */
+    static regexTimeout(pattern: string): DextoRuntimeError;
+    /**
+     * Invalid configuration error
+     */
+    static invalidConfig(reason: string): DextoRuntimeError;
+    /**
+     * Service not initialized error
+     */
+    static notInitialized(): DextoRuntimeError;
+}
+
+export { FileSystemError, type FileSystemErrorContext };

package/dist/errors.d.ts

@@ -0,0 +1,112 @@
+import { DextoRuntimeError } from '@dexto/core';
+
+/**
+ * FileSystem Service Errors
+ *
+ * Error classes for file system operations
+ */
+
+interface FileSystemErrorContext {
+    path?: string;
+    pattern?: string;
+    size?: number;
+    maxSize?: number;
+    encoding?: string;
+    operation?: string;
+}
+/**
+ * Factory class for creating FileSystem-related errors
+ */
+declare class FileSystemError {
+    private constructor();
+    /**
+     * File not found error
+     */
+    static fileNotFound(path: string): DextoRuntimeError;
+    /**
+     * Directory not found error
+     */
+    static directoryNotFound(path: string): DextoRuntimeError;
+    /**
+     * Permission denied error
+     */
+    static permissionDenied(path: string, operation: string): DextoRuntimeError;
+    /**
+     * Path not allowed error
+     */
+    static pathNotAllowed(path: string, allowedPaths: string[]): DextoRuntimeError;
+    /**
+     * Path blocked error
+     */
+    static pathBlocked(path: string, reason: string): DextoRuntimeError;
+    /**
+     * Invalid path error
+     */
+    static invalidPath(path: string, reason: string): DextoRuntimeError;
+    /**
+     * Path traversal detected
+     */
+    static pathTraversal(path: string): DextoRuntimeError;
+    /**
+     * Invalid file extension error
+     */
+    static invalidExtension(path: string, blockedExtensions: string[]): DextoRuntimeError;
+    /**
+     * File too large error
+     */
+    static fileTooLarge(path: string, size: number, maxSize: number): DextoRuntimeError;
+    /**
+     * Too many results error
+     */
+    static tooManyResults(operation: string, count: number, maxResults: number): DextoRuntimeError;
+    /**
+     * Read operation failed
+     */
+    static readFailed(path: string, cause: string): DextoRuntimeError;
+    /**
+     * Write operation failed
+     */
+    static writeFailed(path: string, cause: string): DextoRuntimeError;
+    /**
+     * Backup creation failed
+     */
+    static backupFailed(path: string, cause: string): DextoRuntimeError;
+    /**
+     * Edit operation failed
+     */
+    static editFailed(path: string, cause: string): DextoRuntimeError;
+    /**
+     * String not unique error
+     */
+    static stringNotUnique(path: string, searchString: string, occurrences: number): DextoRuntimeError;
+    /**
+     * String not found error
+     */
+    static stringNotFound(path: string, searchString: string): DextoRuntimeError;
+    /**
+     * Glob operation failed
+     */
+    static globFailed(pattern: string, cause: string): DextoRuntimeError;
+    /**
+     * Search operation failed
+     */
+    static searchFailed(pattern: string, cause: string): DextoRuntimeError;
+    /**
+     * Invalid pattern error
+     */
+    static invalidPattern(pattern: string, cause: string): DextoRuntimeError;
+    /**
+     * Regex timeout error
+     */
+    static regexTimeout(pattern: string): DextoRuntimeError;
+    /**
+     * Invalid configuration error
+     */
+    static invalidConfig(reason: string): DextoRuntimeError;
+    /**
+     * Service not initialized error
+     */
+    static notInitialized(): DextoRuntimeError;
+}
+
+export { FileSystemError, type FileSystemErrorContext };

package/dist/errors.js

@@ -0,0 +1,278 @@
+import { DextoRuntimeError, ErrorScope, ErrorType } from "@dexto/core";
+import { FileSystemErrorCode } from "./error-codes.js";
+class FileSystemError {
+  constructor() {
+  }
+  /**
+   * File not found error
+   */
+  static fileNotFound(path) {
+    return new DextoRuntimeError(
+      FileSystemErrorCode.FILE_NOT_FOUND,
+      ErrorScope.FILESYSTEM,
+      ErrorType.NOT_FOUND,
+      `File not found: ${path}`,
+      { path }
+    );
+  }
+  /**
+   * Directory not found error
+   */
+  static directoryNotFound(path) {
+    return new DextoRuntimeError(
+      FileSystemErrorCode.DIRECTORY_NOT_FOUND,
+      ErrorScope.FILESYSTEM,
+      ErrorType.NOT_FOUND,
+      `Directory not found: ${path}`,
+      { path }
+    );
+  }
+  /**
+   * Permission denied error
+   */
+  static permissionDenied(path, operation) {
+    return new DextoRuntimeError(
+      FileSystemErrorCode.PERMISSION_DENIED,
+      ErrorScope.FILESYSTEM,
+      ErrorType.FORBIDDEN,
+      `Permission denied: cannot ${operation} ${path}`,
+      { path, operation }
+    );
+  }
+  /**
+   * Path not allowed error
+   */
+  static pathNotAllowed(path, allowedPaths) {
+    return new DextoRuntimeError(
+      FileSystemErrorCode.PATH_NOT_ALLOWED,
+      ErrorScope.FILESYSTEM,
+      ErrorType.USER,
+      `Path not allowed: ${path}. Must be within allowed paths: ${allowedPaths.join(", ")}`,
+      { path, allowedPaths },
+      "Ensure the path is within the configured allowed paths"
+    );
+  }
+  /**
+   * Path blocked error
+   */
+  static pathBlocked(path, reason) {
+    return new DextoRuntimeError(
+      FileSystemErrorCode.PATH_BLOCKED,
+      ErrorScope.FILESYSTEM,
+      ErrorType.FORBIDDEN,
+      `Path is blocked: ${path}. Reason: ${reason}`,
+      { path, reason }
+    );
+  }
+  /**
+   * Invalid path error
+   */
+  static invalidPath(path, reason) {
+    return new DextoRuntimeError(
+      FileSystemErrorCode.INVALID_PATH,
+      ErrorScope.FILESYSTEM,
+      ErrorType.USER,
+      `Invalid path: ${path}. ${reason}`,
+      { path, reason }
+    );
+  }
+  /**
+   * Path traversal detected
+   */
+  static pathTraversal(path) {
+    return new DextoRuntimeError(
+      FileSystemErrorCode.PATH_TRAVERSAL_DETECTED,
+      ErrorScope.FILESYSTEM,
+      ErrorType.FORBIDDEN,
+      `Path traversal detected in: ${path}`,
+      { path }
+    );
+  }
+  /**
+   * Invalid file extension error
+   */
+  static invalidExtension(path, blockedExtensions) {
+    return new DextoRuntimeError(
+      FileSystemErrorCode.INVALID_FILE_EXTENSION,
+      ErrorScope.FILESYSTEM,
+      ErrorType.USER,
+      `Invalid file extension: ${path}. Blocked extensions: ${blockedExtensions.join(", ")}`,
+      { path, blockedExtensions }
+    );
+  }
+  /**
+   * File too large error
+   */
+  static fileTooLarge(path, size, maxSize) {
+    return new DextoRuntimeError(
+      FileSystemErrorCode.FILE_TOO_LARGE,
+      ErrorScope.FILESYSTEM,
+      ErrorType.USER,
+      `File too large: ${path} (${size} bytes). Maximum allowed: ${maxSize} bytes`,
+      { path, size, maxSize }
+    );
+  }
+  /**
+   * Too many results error
+   */
+  static tooManyResults(operation, count, maxResults) {
+    return new DextoRuntimeError(
+      FileSystemErrorCode.TOO_MANY_RESULTS,
+      ErrorScope.FILESYSTEM,
+      ErrorType.USER,
+      `Too many results from ${operation}: ${count}. Maximum allowed: ${maxResults}`,
+      { operation, count, maxResults },
+      "Narrow your search pattern or increase maxResults limit"
+    );
+  }
+  /**
+   * Read operation failed
+   */
+  static readFailed(path, cause) {
+    return new DextoRuntimeError(
+      FileSystemErrorCode.READ_FAILED,
+      ErrorScope.FILESYSTEM,
+      ErrorType.SYSTEM,
+      `Failed to read file: ${path}. ${cause}`,
+      { path, cause }
+    );
+  }
+  /**
+   * Write operation failed
+   */
+  static writeFailed(path, cause) {
+    return new DextoRuntimeError(
+      FileSystemErrorCode.WRITE_FAILED,
+      ErrorScope.FILESYSTEM,
+      ErrorType.SYSTEM,
+      `Failed to write file: ${path}. ${cause}`,
+      { path, cause }
+    );
+  }
+  /**
+   * Backup creation failed
+   */
+  static backupFailed(path, cause) {
+    return new DextoRuntimeError(
+      FileSystemErrorCode.BACKUP_FAILED,
+      ErrorScope.FILESYSTEM,
+      ErrorType.SYSTEM,
+      `Failed to create backup for: ${path}. ${cause}`,
+      { path, cause }
+    );
+  }
+  /**
+   * Edit operation failed
+   */
+  static editFailed(path, cause) {
+    return new DextoRuntimeError(
+      FileSystemErrorCode.EDIT_FAILED,
+      ErrorScope.FILESYSTEM,
+      ErrorType.SYSTEM,
+      `Failed to edit file: ${path}. ${cause}`,
+      { path, cause }
+    );
+  }
+  /**
+   * String not unique error
+   */
+  static stringNotUnique(path, searchString, occurrences) {
+    return new DextoRuntimeError(
+      FileSystemErrorCode.STRING_NOT_UNIQUE,
+      ErrorScope.FILESYSTEM,
+      ErrorType.USER,
+      `String is not unique in ${path}: "${searchString}" found ${occurrences} times. Use replaceAll=true or provide a more specific string.`,
+      { path, searchString, occurrences },
+      "Use replaceAll option or provide more context in the search string"
+    );
+  }
+  /**
+   * String not found error
+   */
+  static stringNotFound(path, searchString) {
+    return new DextoRuntimeError(
+      FileSystemErrorCode.STRING_NOT_FOUND,
+      ErrorScope.FILESYSTEM,
+      ErrorType.USER,
+      `String not found in ${path}: "${searchString}"`,
+      { path, searchString }
+    );
+  }
+  /**
+   * Glob operation failed
+   */
+  static globFailed(pattern, cause) {
+    return new DextoRuntimeError(
+      FileSystemErrorCode.GLOB_FAILED,
+      ErrorScope.FILESYSTEM,
+      ErrorType.SYSTEM,
+      `Glob operation failed for pattern: ${pattern}. ${cause}`,
+      { pattern, cause }
+    );
+  }
+  /**
+   * Search operation failed
+   */
+  static searchFailed(pattern, cause) {
+    return new DextoRuntimeError(
+      FileSystemErrorCode.SEARCH_FAILED,
+      ErrorScope.FILESYSTEM,
+      ErrorType.SYSTEM,
+      `Search operation failed for pattern: ${pattern}. ${cause}`,
+      { pattern, cause }
+    );
+  }
+  /**
+   * Invalid pattern error
+   */
+  static invalidPattern(pattern, cause) {
+    return new DextoRuntimeError(
+      FileSystemErrorCode.INVALID_PATTERN,
+      ErrorScope.FILESYSTEM,
+      ErrorType.USER,
+      `Invalid pattern: ${pattern}. ${cause}`,
+      { pattern, cause }
+    );
+  }
+  /**
+   * Regex timeout error
+   */
+  static regexTimeout(pattern) {
+    return new DextoRuntimeError(
+      FileSystemErrorCode.REGEX_TIMEOUT,
+      ErrorScope.FILESYSTEM,
+      ErrorType.TIMEOUT,
+      `Regex operation timed out for pattern: ${pattern}`,
+      { pattern },
+      "Simplify your regex pattern or increase timeout"
+    );
+  }
+  /**
+   * Invalid configuration error
+   */
+  static invalidConfig(reason) {
+    return new DextoRuntimeError(
+      FileSystemErrorCode.INVALID_CONFIG,
+      ErrorScope.FILESYSTEM,
+      ErrorType.USER,
+      `Invalid FileSystem configuration: ${reason}`,
+      { reason }
+    );
+  }
+  /**
+   * Service not initialized error
+   */
+  static notInitialized() {
+    return new DextoRuntimeError(
+      FileSystemErrorCode.SERVICE_NOT_INITIALIZED,
+      ErrorScope.FILESYSTEM,
+      ErrorType.SYSTEM,
+      "FileSystemService has not been initialized",
+      {},
+      "Initialize the FileSystemService before using it"
+    );
+  }
+}
+export {
+  FileSystemError
+};

package/dist/file-tool-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 file_tool_types_exports = {};
+module.exports = __toCommonJS(file_tool_types_exports);

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

@@ -0,0 +1,46 @@
+import { FileSystemService } from './filesystem-service.cjs';
+import '@dexto/core';
+import './types.cjs';
+
+/**
+ * File Tool Types
+ *
+ * Types shared between file tools for directory approval support.
+ */
+
+/**
+ * Callbacks for directory access approval.
+ * Allows file tools to check and request approval for accessing paths
+ * outside the configured working directory.
+ */
+interface DirectoryApprovalCallbacks {
+    /**
+     * Check if a path is within any session-approved directory.
+     * Used to determine if directory approval prompt is needed.
+     * @param filePath The file path to check (absolute or relative)
+     * @returns true if path is in a session-approved directory
+     */
+    isSessionApproved: (filePath: string) => boolean;
+    /**
+     * Add a directory to the approved list for this session.
+     * Called after user approves directory access.
+     * @param directory Absolute path to the directory to approve
+     * @param type 'session' (remembered) or 'once' (single use)
+     */
+    addApproved: (directory: string, type: 'session' | 'once') => void;
+}
+/**
+ * Options for creating file tools with directory approval support
+ */
+interface FileToolOptions {
+    /** FileSystemService instance for file operations */
+    fileSystemService: FileSystemService;
+    /**
+     * Optional callbacks for directory approval.
+     * If provided, file tools can request approval for accessing paths
+     * outside the configured working directory.
+     */
+    directoryApproval?: DirectoryApprovalCallbacks | undefined;
+}
+
+export type { DirectoryApprovalCallbacks, FileToolOptions };

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

@@ -0,0 +1,46 @@
+import { FileSystemService } from './filesystem-service.js';
+import '@dexto/core';
+import './types.js';
+
+/**
+ * File Tool Types
+ *
+ * Types shared between file tools for directory approval support.
+ */
+
+/**
+ * Callbacks for directory access approval.
+ * Allows file tools to check and request approval for accessing paths
+ * outside the configured working directory.
+ */
+interface DirectoryApprovalCallbacks {
+    /**
+     * Check if a path is within any session-approved directory.
+     * Used to determine if directory approval prompt is needed.
+     * @param filePath The file path to check (absolute or relative)
+     * @returns true if path is in a session-approved directory
+     */
+    isSessionApproved: (filePath: string) => boolean;
+    /**
+     * Add a directory to the approved list for this session.
+     * Called after user approves directory access.
+     * @param directory Absolute path to the directory to approve
+     * @param type 'session' (remembered) or 'once' (single use)
+     */
+    addApproved: (directory: string, type: 'session' | 'once') => void;
+}
+/**
+ * Options for creating file tools with directory approval support
+ */
+interface FileToolOptions {
+    /** FileSystemService instance for file operations */
+    fileSystemService: FileSystemService;
+    /**
+     * Optional callbacks for directory approval.
+     * If provided, file tools can request approval for accessing paths
+     * outside the configured working directory.
+     */
+    directoryApproval?: DirectoryApprovalCallbacks | undefined;
+}
+
+export type { DirectoryApprovalCallbacks, FileToolOptions };