@dexto/tools-filesystem 1.6.0 → 1.6.2

package/dist/errors.d.cts

@@ -1,112 +0,0 @@
-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/file-tool-types.d.cts

@@ -1,18 +0,0 @@
-import { ToolExecutionContext } from '@dexto/core';
-import { FileSystemService } from './filesystem-service.cjs';
-import './types.cjs';
-
-/**
- * File Tool Types
- *
- * Types shared between file tools and factories.
- */
-
-/**
- * Getter for a lazily-initialized {@link FileSystemService}.
- * Tool factories construct tools before runtime services are available, so tools
- * resolve the service on-demand using {@link ToolExecutionContext}.
- */
-type FileSystemServiceGetter = (context: ToolExecutionContext) => Promise<FileSystemService>;
-
-export type { FileSystemServiceGetter };

package/dist/filesystem-service.d.cts

@@ -1,117 +0,0 @@
-import { Logger } from '@dexto/core';
-import { FileSystemConfig, ReadFileOptions, FileContent, GlobOptions, GlobResult, GrepOptions, SearchResult, WriteFileOptions, WriteResult, EditOperation, EditFileOptions, EditResult } from './types.cjs';
-
-/**
- * FileSystem Service
- *
- * Secure file system operations for Dexto internal tools
- */
-
-/**
- * FileSystemService - Handles all file system operations with security checks
- *
- * This service receives fully-validated configuration from the FileSystem Tools Factory.
- * All defaults have been applied by the factory's schema, so the service trusts the config
- * and uses it as-is without any fallback logic.
- *
- * TODO: instantiate only when internal file tools are enabled to avoid file dependencies which won't work in serverless
- */
-declare class FileSystemService {
-    private config;
-    private pathValidator;
-    private initialized;
-    private initPromise;
-    private logger;
-    private directoryApprovalChecker?;
-    /**
-     * Create a new FileSystemService with validated configuration.
-     *
-     * @param config - Fully-validated configuration from the factory schema.
-     *                 All required fields have values, defaults already applied.
-     * @param logger - Logger instance for this service
-     */
-    constructor(config: FileSystemConfig, logger: Logger);
-    /**
-     * Get backup directory path (context-aware with optional override)
-     * TODO: Migrate to explicit configuration via CLI enrichment layer (per-agent paths)
-     */
-    private getBackupDir;
-    /**
-     * Get the effective working directory for file operations.
-     * Falls back to process.cwd() if not configured.
-     */
-    getWorkingDirectory(): string;
-    /**
-     * Initialize the service.
-     * Safe to call multiple times - subsequent calls return the same promise.
-     */
-    initialize(): Promise<void>;
-    /**
-     * Internal initialization logic.
-     */
-    private doInitialize;
-    /**
-     * Ensure the service is initialized before use.
-     * Tools should call this at the start of their execute methods.
-     * Safe to call multiple times - will await the same initialization promise.
-     */
-    ensureInitialized(): Promise<void>;
-    /**
-     * Set a callback to check if a path is in an approved directory.
-     * This allows PathValidator to consult ApprovalManager without a direct dependency.
-     *
-     * @param checker Function that returns true if path is in an approved directory
-     */
-    setDirectoryApprovalChecker(checker: (filePath: string) => boolean): void;
-    /**
-     * Update the working directory at runtime (e.g., when workspace changes).
-     * Rebuilds the PathValidator so allowed/blocked path roots are recalculated.
-     */
-    setWorkingDirectory(workingDirectory: string): void;
-    /**
-     * Check if a file path is within the configured allowed paths (config only).
-     * This is used by file tools to determine if directory approval is needed.
-     *
-     * @param filePath The file path to check (can be relative or absolute)
-     * @returns true if the path is within config-allowed paths, false otherwise
-     */
-    isPathWithinConfigAllowed(filePath: string): Promise<boolean>;
-    /**
-     * Read a file with validation and size limits
-     */
-    readFile(filePath: string, options?: ReadFileOptions): Promise<FileContent>;
-    /**
-     * Find files matching a glob pattern
-     */
-    globFiles(pattern: string, options?: GlobOptions): Promise<GlobResult>;
-    /**
-     * Search for content in files (grep-like functionality)
-     */
-    searchContent(pattern: string, options?: GrepOptions): Promise<SearchResult>;
-    /**
-     * Write content to a file
-     */
-    writeFile(filePath: string, content: string, options?: WriteFileOptions): Promise<WriteResult>;
-    /**
-     * Edit a file by replacing text
-     */
-    editFile(filePath: string, operation: EditOperation, options?: EditFileOptions): Promise<EditResult>;
-    /**
-     * Create a backup of a file
-     */
-    private createBackup;
-    /**
-     * Clean up old backup files based on retention policy
-     */
-    cleanupOldBackups(): Promise<number>;
-    /**
-     * Get service configuration
-     */
-    getConfig(): Readonly<FileSystemConfig>;
-    /**
-     * Check if a path is allowed (async for non-blocking symlink resolution)
-     */
-    isPathAllowed(filePath: string): Promise<boolean>;
-}
-
-export { FileSystemService };

package/dist/filesystem-service.test.d.cts

@@ -1,2 +0,0 @@
-
-export {  }

package/dist/glob-files-tool.d.cts

@@ -1,31 +0,0 @@
-import { z } from 'zod';
-import { Tool } from '@dexto/core';
-import { FileSystemServiceGetter } from './file-tool-types.cjs';
-import './filesystem-service.cjs';
-import './types.cjs';
-
-/**
- * Glob Files Tool
- *
- * Internal tool for finding files using glob patterns
- */
-
-declare const GlobFilesInputSchema: z.ZodObject<{
-    pattern: z.ZodString;
-    path: z.ZodOptional<z.ZodString>;
-    max_results: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
-}, "strict", z.ZodTypeAny, {
-    pattern: string;
-    max_results: number;
-    path?: string | undefined;
-}, {
-    pattern: string;
-    path?: string | undefined;
-    max_results?: number | undefined;
-}>;
-/**
- * Create the glob_files internal tool with directory approval support
- */
-declare function createGlobFilesTool(getFileSystemService: FileSystemServiceGetter): Tool<typeof GlobFilesInputSchema>;
-
-export { createGlobFilesTool };

package/dist/grep-content-tool.d.cts

@@ -1,40 +0,0 @@
-import { z } from 'zod';
-import { Tool } from '@dexto/core';
-import { FileSystemServiceGetter } from './file-tool-types.cjs';
-import './filesystem-service.cjs';
-import './types.cjs';
-
-/**
- * Grep Content Tool
- *
- * Internal tool for searching file contents using regex patterns
- */
-
-declare const GrepContentInputSchema: z.ZodObject<{
-    pattern: z.ZodString;
-    path: z.ZodOptional<z.ZodString>;
-    glob: z.ZodOptional<z.ZodString>;
-    context_lines: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
-    case_insensitive: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
-    max_results: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
-}, "strict", z.ZodTypeAny, {
-    pattern: string;
-    max_results: number;
-    context_lines: number;
-    case_insensitive: boolean;
-    path?: string | undefined;
-    glob?: string | undefined;
-}, {
-    pattern: string;
-    path?: string | undefined;
-    max_results?: number | undefined;
-    glob?: string | undefined;
-    context_lines?: number | undefined;
-    case_insensitive?: boolean | undefined;
-}>;
-/**
- * Create the grep_content internal tool with directory approval support
- */
-declare function createGrepContentTool(getFileSystemService: FileSystemServiceGetter): Tool<typeof GrepContentInputSchema>;
-
-export { createGrepContentTool };

package/dist/path-validator.d.cts

@@ -1,97 +0,0 @@
-import { FileSystemConfig, PathValidation } from './types.cjs';
-import { Logger } from '@dexto/core';
-
-/**
- * Path Validator
- *
- * Security-focused path validation for file system operations
- */
-
-/**
- * Callback type for checking if a path is in an approved directory.
- * Used to consult ApprovalManager without creating a direct dependency.
- */
-type DirectoryApprovalChecker = (filePath: string) => boolean;
-/**
- * PathValidator - Validates file paths for security and policy compliance
- *
- * Security checks:
- * 1. Path traversal detection (../, symbolic links)
- * 2. Allowed paths enforcement (whitelist + approved directories)
- * 3. Blocked paths detection (blacklist)
- * 4. File extension restrictions
- * 5. Absolute path normalization
- *
- * PathValidator can optionally consult an external approval checker (e.g., ApprovalManager)
- * to determine if paths outside the config's allowed paths are accessible.
- */
-declare class PathValidator {
-    private config;
-    private normalizedAllowedPaths;
-    private normalizedBlockedPaths;
-    private normalizedBlockedExtensions;
-    private logger;
-    private directoryApprovalChecker;
-    constructor(config: FileSystemConfig, logger: Logger);
-    /**
-     * Set a callback to check if a path is in an approved directory.
-     * This allows PathValidator to consult ApprovalManager without a direct dependency.
-     *
-     * @param checker Function that returns true if path is in an approved directory
-     */
-    setDirectoryApprovalChecker(checker: DirectoryApprovalChecker): void;
-    /**
-     * Validate a file path for security and policy compliance
-     */
-    validatePath(filePath: string): Promise<PathValidation>;
-    /**
-     * Check if path contains traversal attempts
-     */
-    private hasPathTraversal;
-    /**
-     * Check if path is within allowed paths (whitelist check)
-     * Also consults the directory approval checker if configured.
-     * Uses the sync version since the path is already normalized at this point.
-     */
-    private isPathAllowed;
-    /**
-     * Check if path matches blocked patterns (blacklist check)
-     */
-    private isPathBlocked;
-    /**
-     * Quick check if a path is allowed (for internal use)
-     * Note: This assumes the path is already normalized/canonicalized
-     */
-    isPathAllowedQuick(normalizedPath: string): boolean;
-    /**
-     * Synchronous path allowed check (for already-normalized paths)
-     * This is used internally when we already have a canonicalized path
-     */
-    private isPathAllowedSync;
-    /**
-     * Check if a file path is within the configured allowed paths (from config only).
-     * This method does NOT consult ApprovalManager - it only checks the static config paths.
-     *
-     * This is used by file tools to determine if a path needs directory approval.
-     * Paths within config-allowed directories don't need directory approval prompts.
-     *
-     * @param filePath The file path to check (can be relative or absolute)
-     * @returns true if the path is within config-allowed paths, false otherwise
-     */
-    isPathWithinAllowed(filePath: string): Promise<boolean>;
-    /**
-     * Check if path is within config-allowed paths only (no approval checker).
-     * Used for prompting decisions.
-     */
-    private isInConfigAllowedPaths;
-    /**
-     * Get normalized allowed paths
-     */
-    getAllowedPaths(): string[];
-    /**
-     * Get blocked paths
-     */
-    getBlockedPaths(): string[];
-}
-
-export { type DirectoryApprovalChecker, PathValidator };

package/dist/path-validator.test.d.cts

@@ -1,2 +0,0 @@
-
-export {  }

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

@@ -1,31 +0,0 @@
-import { z } from 'zod';
-import { Tool } from '@dexto/core';
-import { FileSystemServiceGetter } 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
- */
-
-declare const ReadFileInputSchema: z.ZodObject<{
-    file_path: z.ZodString;
-    limit: z.ZodOptional<z.ZodNumber>;
-    offset: z.ZodOptional<z.ZodNumber>;
-}, "strict", z.ZodTypeAny, {
-    file_path: string;
-    limit?: number | undefined;
-    offset?: number | undefined;
-}, {
-    file_path: string;
-    limit?: number | undefined;
-    offset?: number | undefined;
-}>;
-/**
- * Create the read_file internal tool with directory approval support
- */
-declare function createReadFileTool(getFileSystemService: FileSystemServiceGetter): Tool<typeof ReadFileInputSchema>;
-
-export { createReadFileTool };

package/dist/tool-factory-config.d.cts

@@ -1,63 +0,0 @@
-import { z } from 'zod';
-
-/**
- * FileSystem Tools Factory
- *
- * Provides file operation tools by wrapping FileSystemService.
- * When registered, the factory initializes FileSystemService and creates tools
- * for file operations (read, write, edit, glob, grep).
- */
-
-/**
- * Available filesystem tool names for enabledTools configuration.
- */
-declare const FILESYSTEM_TOOL_NAMES: readonly ["read_file", "write_file", "edit_file", "glob_files", "grep_content"];
-/**
- * Configuration schema for FileSystem tools factory.
- *
- * 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>;
-    enabledTools: z.ZodOptional<z.ZodArray<z.ZodEnum<["read_file", "write_file", "edit_file", "glob_files", "grep_content"]>, "many">>;
-}, "strict", z.ZodTypeAny, {
-    type: "filesystem-tools";
-    allowedPaths: string[];
-    blockedExtensions: string[];
-    blockedPaths: string[];
-    maxFileSize: number;
-    enableBackups: boolean;
-    backupRetentionDays: number;
-    backupPath?: string | undefined;
-    workingDirectory?: string | undefined;
-    enabledTools?: ("edit_file" | "glob_files" | "grep_content" | "read_file" | "write_file")[] | 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;
-    enabledTools?: ("edit_file" | "glob_files" | "grep_content" | "read_file" | "write_file")[] | undefined;
-}>;
-type FileSystemToolsConfig = z.output<typeof FileSystemToolsConfigSchema>;
-
-export { FILESYSTEM_TOOL_NAMES, type FileSystemToolsConfig, FileSystemToolsConfigSchema };

package/dist/tool-factory.d.cts

@@ -1,7 +0,0 @@
-import { ToolFactory } from '@dexto/agent-config';
-import { FileSystemToolsConfig } from './tool-factory-config.cjs';
-import 'zod';
-
-declare const fileSystemToolsFactory: ToolFactory<FileSystemToolsConfig>;
-
-export { fileSystemToolsFactory };