@j0hanz/filesystem-context-mcp 1.0.0

package/dist/lib/constants.js

@@ -0,0 +1,335 @@
+// Concurrency limits
+export const PARALLEL_CONCURRENCY = 20;
+export const DIR_TRAVERSAL_CONCURRENCY = 8;
+// Timeout limits (in milliseconds)
+export const REGEX_MATCH_TIMEOUT_MS = 100; // Per-line regex match timeout to prevent ReDoS hangs
+// Size limits (in bytes)
+export const MAX_SEARCHABLE_FILE_SIZE = 1024 * 1024; // 1MB
+export const MAX_TEXT_FILE_SIZE = 10 * 1024 * 1024; // 10MB default for text files
+export const MAX_MEDIA_FILE_SIZE = 50 * 1024 * 1024; // 50MB default for media files
+export const MAX_LINE_CONTENT_LENGTH = 200;
+export const BINARY_CHECK_BUFFER_SIZE = 512; // Increased for better accuracy
+// Default limits for operations
+export const DEFAULT_MAX_DEPTH = 10;
+export const DEFAULT_MAX_RESULTS = 100;
+export const DEFAULT_TOP_N = 10;
+export const DEFAULT_TREE_DEPTH = 5;
+// Known text file extensions for fast-path binary detection
+export const KNOWN_TEXT_EXTENSIONS = new Set([
+    '.ts',
+    '.tsx',
+    '.js',
+    '.jsx',
+    '.mjs',
+    '.cjs',
+    '.json',
+    '.jsonc',
+    '.json5',
+    '.md',
+    '.mdx',
+    '.markdown',
+    '.txt',
+    '.text',
+    '.log',
+    '.html',
+    '.htm',
+    '.xhtml',
+    '.css',
+    '.scss',
+    '.sass',
+    '.less',
+    '.styl',
+    '.yaml',
+    '.yml',
+    '.xml',
+    '.xsl',
+    '.xslt',
+    '.svg',
+    '.sh',
+    '.bash',
+    '.zsh',
+    '.fish',
+    '.ps1',
+    '.psm1',
+    '.psd1',
+    '.bat',
+    '.cmd',
+    '.py',
+    '.pyw',
+    '.pyi',
+    '.pyx',
+    '.rb',
+    '.rake',
+    '.gemspec',
+    '.go',
+    '.mod',
+    '.sum',
+    '.rs',
+    '.c',
+    '.h',
+    '.cpp',
+    '.hpp',
+    '.cc',
+    '.hh',
+    '.cxx',
+    '.hxx',
+    '.java',
+    '.kt',
+    '.kts',
+    '.scala',
+    '.groovy',
+    '.gradle',
+    '.swift',
+    '.php',
+    '.phtml',
+    '.sql',
+    '.mysql',
+    '.pgsql',
+    '.graphql',
+    '.gql',
+    '.vue',
+    '.svelte',
+    '.astro',
+    '.toml',
+    '.ini',
+    '.cfg',
+    '.conf',
+    '.config',
+    '.env',
+    '.env.local',
+    '.env.development',
+    '.env.production',
+    '.gitignore',
+    '.gitattributes',
+    '.npmignore',
+    '.dockerignore',
+    '.editorconfig',
+    '.prettierrc',
+    '.eslintrc',
+    '.lock', // package-lock.json, yarn.lock, etc. are text
+    '.csv',
+    '.tsv',
+    '.rst',
+    '.asciidoc',
+    '.adoc',
+    '.tex',
+    '.latex',
+    '.bib',
+    '.r',
+    '.R',
+    '.rmd',
+    '.lua',
+    '.pl',
+    '.pm',
+    '.perl',
+    '.asm',
+    '.s',
+    '.dart',
+    '.elm',
+    '.ex',
+    '.exs',
+    '.erl',
+    '.hrl',
+    '.hs',
+    '.lhs',
+    '.clj',
+    '.cljs',
+    '.cljc',
+    '.edn',
+    '.lisp',
+    '.cl',
+    '.el',
+    '.ml',
+    '.mli',
+    '.fs',
+    '.fsi',
+    '.fsx',
+    '.nim',
+    '.v',
+    '.sv',
+    '.vhd',
+    '.vhdl',
+    '.proto',
+    '.tf',
+    '.tfvars',
+    '.hcl',
+    '.cmake',
+    '.makefile',
+    '.mk',
+    '.dockerfile',
+    '.containerfile',
+]);
+// Known binary file extensions for fast-path binary detection
+export const KNOWN_BINARY_EXTENSIONS = new Set([
+    // Images
+    '.png',
+    '.jpg',
+    '.jpeg',
+    '.gif',
+    '.webp',
+    '.ico',
+    '.bmp',
+    '.tiff',
+    '.tif',
+    '.psd',
+    '.ai',
+    '.eps',
+    '.raw',
+    '.cr2',
+    '.nef',
+    '.heic',
+    '.heif',
+    '.avif',
+    // Audio
+    '.mp3',
+    '.wav',
+    '.flac',
+    '.aac',
+    '.ogg',
+    '.wma',
+    '.m4a',
+    '.opus',
+    '.aiff',
+    // Video
+    '.mp4',
+    '.avi',
+    '.mov',
+    '.wmv',
+    '.flv',
+    '.mkv',
+    '.webm',
+    '.m4v',
+    '.mpeg',
+    '.mpg',
+    // Archives
+    '.zip',
+    '.tar',
+    '.gz',
+    '.bz2',
+    '.xz',
+    '.7z',
+    '.rar',
+    '.cab',
+    '.iso',
+    '.dmg',
+    // Executables & Libraries
+    '.exe',
+    '.dll',
+    '.so',
+    '.dylib',
+    '.a',
+    '.lib',
+    '.o',
+    '.obj',
+    '.app',
+    '.msi',
+    '.deb',
+    '.rpm',
+    '.apk',
+    '.ipa',
+    // Fonts
+    '.ttf',
+    '.otf',
+    '.woff',
+    '.woff2',
+    '.eot',
+    // Documents (binary formats)
+    '.pdf',
+    '.doc',
+    '.docx',
+    '.xls',
+    '.xlsx',
+    '.ppt',
+    '.pptx',
+    '.odt',
+    '.ods',
+    '.odp',
+    // Databases
+    '.sqlite',
+    '.sqlite3',
+    '.db',
+    '.mdb',
+    '.accdb',
+    // WebAssembly
+    '.wasm',
+    // Other binary
+    '.bin',
+    '.dat',
+    '.pak',
+    '.bundle',
+    '.class',
+    '.pyc',
+    '.pyo',
+    '.node',
+    '.napi',
+    // Source maps (can be large and not useful for text search)
+    '.map',
+]);
+// MIME type mappings for media files
+export const MIME_TYPES = {
+    // Images
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.gif': 'image/gif',
+    '.webp': 'image/webp',
+    '.svg': 'image/svg+xml',
+    '.ico': 'image/x-icon',
+    '.bmp': 'image/bmp',
+    '.tiff': 'image/tiff',
+    '.tif': 'image/tiff',
+    '.avif': 'image/avif',
+    '.heic': 'image/heic',
+    '.heif': 'image/heif',
+    // Audio
+    '.mp3': 'audio/mpeg',
+    '.wav': 'audio/wav',
+    '.ogg': 'audio/ogg',
+    '.flac': 'audio/flac',
+    '.aac': 'audio/aac',
+    '.m4a': 'audio/mp4',
+    '.wma': 'audio/x-ms-wma',
+    '.opus': 'audio/opus',
+    // Video
+    '.mp4': 'video/mp4',
+    '.webm': 'video/webm',
+    '.avi': 'video/x-msvideo',
+    '.mov': 'video/quicktime',
+    '.wmv': 'video/x-ms-wmv',
+    '.mkv': 'video/x-matroska',
+    '.flv': 'video/x-flv',
+    // Documents
+    '.pdf': 'application/pdf',
+    // Common text (best-effort)
+    '.txt': 'text/plain',
+    '.log': 'text/plain',
+    '.md': 'text/markdown',
+    '.markdown': 'text/markdown',
+    '.json': 'application/json',
+    '.jsonc': 'application/json',
+    '.xml': 'application/xml',
+    '.yaml': 'text/yaml',
+    '.yml': 'text/yaml',
+    '.html': 'text/html',
+    '.htm': 'text/html',
+    '.css': 'text/css',
+    '.js': 'text/javascript',
+    '.mjs': 'text/javascript',
+    '.cjs': 'text/javascript',
+    '.ts': 'text/typescript',
+    '.tsx': 'text/typescript',
+    // Archives
+    '.zip': 'application/zip',
+    '.tar': 'application/x-tar',
+    '.gz': 'application/gzip',
+    '.7z': 'application/x-7z-compressed',
+    '.rar': 'application/vnd.rar',
+    // Fonts
+    '.ttf': 'font/ttf',
+    '.otf': 'font/otf',
+    '.woff': 'font/woff',
+    '.woff2': 'font/woff2',
+    // Other
+    '.wasm': 'application/wasm',
+};
+//# sourceMappingURL=constants.js.map

package/dist/lib/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../src/lib/constants.ts"],"names":[],"mappings":"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"}

package/dist/lib/errors.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Structured error handling utilities for consistent error responses
+ */
+import { type DetailedError, ErrorCode, type ErrorResponse } from '../config/types.js';
+export { ErrorCode };
+export declare class McpError extends Error {
+    code: ErrorCode;
+    path?: string | undefined;
+    details?: Record<string, unknown> | undefined;
+    constructor(code: ErrorCode, message: string, path?: string | undefined, details?: Record<string, unknown> | undefined, cause?: unknown);
+    /**
+     * Create an McpError from an existing error with proper cause chaining
+     */
+    static fromError(code: ErrorCode, message: string, originalError: unknown, path?: string, details?: Record<string, unknown>): McpError;
+}
+/**
+ * Classify an error into an appropriate error code based on message patterns and Node.js error codes
+ */
+export declare function classifyError(error: unknown): ErrorCode;
+/**
+ * Create a detailed error object with suggestions
+ */
+export declare function createDetailedError(error: unknown, path?: string, additionalDetails?: Record<string, unknown>): DetailedError;
+/**
+ * Format a detailed error for display
+ */
+export declare function formatDetailedError(error: DetailedError): string;
+/**
+ * Get suggestion for an error code
+ */
+export declare function getSuggestion(code: ErrorCode): string;
+export declare function createErrorResponse(error: unknown, defaultCode: ErrorCode, path?: string): ErrorResponse;
+//# sourceMappingURL=errors.d.ts.map

package/dist/lib/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/lib/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EACL,KAAK,aAAa,EAClB,SAAS,EACT,KAAK,aAAa,EACnB,MAAM,oBAAoB,CAAC;AAG5B,OAAO,EAAE,SAAS,EAAE,CAAC;AAErB,qBAAa,QAAS,SAAQ,KAAK;IAExB,IAAI,EAAE,SAAS;IAEf,IAAI,CAAC,EAAE,MAAM;IACb,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;gBAHjC,IAAI,EAAE,SAAS,EACtB,OAAO,EAAE,MAAM,EACR,IAAI,CAAC,EAAE,MAAM,YAAA,EACb,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,YAAA,EACxC,KAAK,CAAC,EAAE,OAAO;IAQjB;;OAEG;IACH,MAAM,CAAC,SAAS,CACd,IAAI,EAAE,SAAS,EACf,OAAO,EAAE,MAAM,EACf,aAAa,EAAE,OAAO,EACtB,IAAI,CAAC,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC,QAAQ;CAQZ;AAkCD;;GAEG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,SAAS,CAmHvD;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,OAAO,EACd,IAAI,CAAC,EAAE,MAAM,EACb,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC1C,aAAa,CAmBf;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,CAYhE;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,CAErD;AAED,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,OAAO,EACd,WAAW,EAAE,SAAS,EACtB,IAAI,CAAC,EAAE,MAAM,GACZ,aAAa,CAoBf"}

package/dist/lib/errors.js

@@ -0,0 +1,205 @@
+/**
+ * Structured error handling utilities for consistent error responses
+ */
+import { ErrorCode, } from '../config/types.js';
+// Re-export ErrorCode from centralized location
+export { ErrorCode };
+export class McpError extends Error {
+    code;
+    path;
+    details;
+    constructor(code, message, path, details, cause) {
+        super(message, { cause });
+        this.code = code;
+        this.path = path;
+        this.details = details;
+        this.name = 'McpError';
+        // Ensure proper prototype chain for instanceof checks
+        Object.setPrototypeOf(this, McpError.prototype);
+    }
+    /**
+     * Create an McpError from an existing error with proper cause chaining
+     */
+    static fromError(code, message, originalError, path, details) {
+        const mcpError = new McpError(code, message, path, details, originalError);
+        // Preserve stack trace if available
+        if (originalError instanceof Error && originalError.stack) {
+            mcpError.stack = `${String(mcpError.stack)}\nCaused by: ${originalError.stack}`;
+        }
+        return mcpError;
+    }
+}
+/**
+ * Mapping of error codes to actionable suggestions for users
+ */
+const ERROR_SUGGESTIONS = {
+    [ErrorCode.E_ACCESS_DENIED]: 'Check that the path is within an allowed directory. Use list_allowed_directories to see available paths.',
+    [ErrorCode.E_NOT_FOUND]: 'Verify the path exists. Use list_directory to explore available files and directories.',
+    [ErrorCode.E_NOT_FILE]: 'The path points to a directory or other non-file. Use list_directory to explore its contents.',
+    [ErrorCode.E_NOT_DIRECTORY]: 'The path points to a file, not a directory. Use read_file to read file contents.',
+    [ErrorCode.E_TOO_LARGE]: 'The file exceeds the size limit. Use head or tail parameters to read partial content, or increase maxSize.',
+    [ErrorCode.E_BINARY_FILE]: 'This appears to be a binary file. Use read_media_file for images/audio, or set skipBinary=false to include.',
+    [ErrorCode.E_TIMEOUT]: 'The operation timed out. Try with a smaller scope, fewer files, or increase timeoutMs.',
+    [ErrorCode.E_INVALID_PATTERN]: 'The glob or regex pattern is invalid. Check syntax and escape special characters.',
+    [ErrorCode.E_INVALID_INPUT]: 'One or more input parameters are invalid. Check the tool documentation for correct usage.',
+    [ErrorCode.E_PERMISSION_DENIED]: 'Permission denied by the operating system. Check file permissions.',
+    [ErrorCode.E_SYMLINK_NOT_ALLOWED]: 'Symbolic links that escape allowed directories are not permitted for security reasons.',
+    [ErrorCode.E_PATH_TRAVERSAL]: 'Path traversal attempts (../) that escape allowed directories are not permitted.',
+    [ErrorCode.E_UNKNOWN]: 'An unexpected error occurred. Check the error message for details.',
+};
+/**
+ * Classify an error into an appropriate error code based on message patterns and Node.js error codes
+ */
+export function classifyError(error) {
+    if (error instanceof McpError) {
+        return error.code;
+    }
+    // Extract Node.js error code if available
+    const nodeErrorCode = error instanceof Error && 'code' in error
+        ? error.code
+        : undefined;
+    // Classify by Node.js error code first (most reliable)
+    if (nodeErrorCode) {
+        switch (nodeErrorCode) {
+            case 'ENOENT':
+                return ErrorCode.E_NOT_FOUND;
+            case 'EACCES':
+            case 'EPERM':
+                return ErrorCode.E_PERMISSION_DENIED;
+            case 'ENOTDIR':
+                return ErrorCode.E_NOT_DIRECTORY;
+            case 'EISDIR':
+                return ErrorCode.E_NOT_FILE;
+            case 'ELOOP':
+                return ErrorCode.E_SYMLINK_NOT_ALLOWED;
+            case 'ENAMETOOLONG':
+                return ErrorCode.E_INVALID_INPUT;
+            case 'ETIMEDOUT':
+                return ErrorCode.E_TIMEOUT;
+            case 'EMFILE':
+            case 'ENFILE':
+                // Too many open files - treat as timeout/resource exhaustion
+                return ErrorCode.E_TIMEOUT;
+            case 'EBUSY':
+                return ErrorCode.E_PERMISSION_DENIED;
+            case 'ENOTEMPTY':
+                return ErrorCode.E_NOT_DIRECTORY;
+        }
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    const lowerMessage = message.toLowerCase();
+    if (lowerMessage.includes('not within allowed') ||
+        lowerMessage.includes('access denied') ||
+        lowerMessage.includes('outside allowed')) {
+        return ErrorCode.E_ACCESS_DENIED;
+    }
+    if (lowerMessage.includes('enoent') ||
+        lowerMessage.includes('not found') ||
+        lowerMessage.includes('does not exist') ||
+        lowerMessage.includes('no such file')) {
+        return ErrorCode.E_NOT_FOUND;
+    }
+    if (lowerMessage.includes('not a file') ||
+        lowerMessage.includes('is a directory') ||
+        lowerMessage.includes('eisdir')) {
+        return ErrorCode.E_NOT_FILE;
+    }
+    if (lowerMessage.includes('not a directory') ||
+        lowerMessage.includes('enotdir')) {
+        return ErrorCode.E_NOT_DIRECTORY;
+    }
+    if (lowerMessage.includes('too large') ||
+        lowerMessage.includes('exceeds') ||
+        lowerMessage.includes('file size')) {
+        return ErrorCode.E_TOO_LARGE;
+    }
+    if (lowerMessage.includes('binary')) {
+        return ErrorCode.E_BINARY_FILE;
+    }
+    if (lowerMessage.includes('timeout') || lowerMessage.includes('etimedout')) {
+        return ErrorCode.E_TIMEOUT;
+    }
+    if (lowerMessage.includes('invalid') &&
+        (lowerMessage.includes('pattern') ||
+            lowerMessage.includes('regex') ||
+            lowerMessage.includes('regexp') ||
+            lowerMessage.includes('glob'))) {
+        return ErrorCode.E_INVALID_PATTERN;
+    }
+    if (lowerMessage.includes('invalid') ||
+        lowerMessage.includes('cannot specify multiple') ||
+        lowerMessage.includes('must be')) {
+        return ErrorCode.E_INVALID_INPUT;
+    }
+    if (lowerMessage.includes('eacces') ||
+        lowerMessage.includes('eperm') ||
+        lowerMessage.includes('permission')) {
+        return ErrorCode.E_PERMISSION_DENIED;
+    }
+    if (lowerMessage.includes('symlink') || lowerMessage.includes('eloop')) {
+        return ErrorCode.E_SYMLINK_NOT_ALLOWED;
+    }
+    if (lowerMessage.includes('traversal')) {
+        return ErrorCode.E_PATH_TRAVERSAL;
+    }
+    return ErrorCode.E_UNKNOWN;
+}
+/**
+ * Create a detailed error object with suggestions
+ */
+export function createDetailedError(error, path, additionalDetails) {
+    const message = error instanceof Error ? error.message : String(error);
+    const code = classifyError(error);
+    const suggestion = ERROR_SUGGESTIONS[code];
+    const effectivePath = path ?? (error instanceof McpError ? error.path : undefined);
+    const mergedDetails = {
+        ...(error instanceof McpError ? error.details : undefined),
+        ...(additionalDetails ?? undefined),
+    };
+    return {
+        code,
+        message,
+        path: effectivePath,
+        suggestion,
+        details: Object.keys(mergedDetails).length > 0 ? mergedDetails : undefined,
+    };
+}
+/**
+ * Format a detailed error for display
+ */
+export function formatDetailedError(error) {
+    const lines = [`Error [${error.code}]: ${error.message}`];
+    if (error.path) {
+        lines.push(`Path: ${error.path}`);
+    }
+    if (error.suggestion) {
+        lines.push(`Suggestion: ${error.suggestion}`);
+    }
+    return lines.join('\n');
+}
+/**
+ * Get suggestion for an error code
+ */
+export function getSuggestion(code) {
+    return ERROR_SUGGESTIONS[code];
+}
+export function createErrorResponse(error, defaultCode, path) {
+    const detailed = createDetailedError(error, path);
+    // Use more specific code if classified, otherwise use default
+    const finalCode = detailed.code === ErrorCode.E_UNKNOWN ? defaultCode : detailed.code;
+    detailed.code = finalCode;
+    return {
+        content: [{ type: 'text', text: formatDetailedError(detailed) }],
+        structuredContent: {
+            ok: false,
+            error: {
+                code: detailed.code,
+                message: detailed.message,
+                path: detailed.path,
+                suggestion: detailed.suggestion,
+            },
+        },
+        isError: true,
+    };
+}
+//# sourceMappingURL=errors.js.map

package/dist/lib/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/lib/errors.ts"],"names":[],"mappings":"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"}

package/dist/lib/file-operations.d.ts

@@ -0,0 +1,69 @@
+import type { AnalyzeDirectoryResult, DirectoryTreeResult, FileInfo, ListDirectoryResult, MediaFileResult, SearchContentResult, SearchFilesResult } from '../config/types.js';
+import { readFile } from './fs-helpers.js';
+export declare function getFileInfo(filePath: string): Promise<FileInfo>;
+export declare function listDirectory(dirPath: string, options?: {
+    recursive?: boolean;
+    includeHidden?: boolean;
+    maxDepth?: number;
+    maxEntries?: number;
+    sortBy?: 'name' | 'size' | 'modified' | 'type';
+    includeSymlinkTargets?: boolean;
+}): Promise<ListDirectoryResult>;
+export declare function searchFiles(basePath: string, pattern: string, excludePatterns?: string[], options?: {
+    maxResults?: number;
+    sortBy?: 'name' | 'size' | 'modified' | 'path';
+    maxDepth?: number;
+}): Promise<SearchFilesResult>;
+export { readFile };
+/**
+ * Read multiple files in parallel.
+ * Individual file errors don't fail the entire operation.
+ */
+export declare function readMultipleFiles(filePaths: string[], options?: {
+    encoding?: BufferEncoding;
+    maxSize?: number;
+    head?: number;
+    tail?: number;
+}): Promise<{
+    path: string;
+    content?: string;
+    error?: string;
+}[]>;
+export declare function searchContent(basePath: string, searchPattern: string, options?: {
+    filePattern?: string;
+    excludePatterns?: string[];
+    caseSensitive?: boolean;
+    maxResults?: number;
+    maxFileSize?: number;
+    maxFilesScanned?: number;
+    timeoutMs?: number;
+    skipBinary?: boolean;
+    contextLines?: number;
+    wholeWord?: boolean;
+    isLiteral?: boolean;
+}): Promise<SearchContentResult>;
+export declare function analyzeDirectory(dirPath: string, options?: {
+    maxDepth?: number;
+    topN?: number;
+    excludePatterns?: string[];
+    includeHidden?: boolean;
+}): Promise<AnalyzeDirectoryResult>;
+/**
+ * Build a JSON tree structure of a directory.
+ * More efficient for AI parsing than flat file lists.
+ */
+export declare function getDirectoryTree(dirPath: string, options?: {
+    maxDepth?: number;
+    excludePatterns?: string[];
+    includeHidden?: boolean;
+    includeSize?: boolean;
+    maxFiles?: number;
+}): Promise<DirectoryTreeResult>;
+/**
+ * Read a media/binary file and return as base64.
+ * Useful for images, audio, and other binary content.
+ */
+export declare function readMediaFile(filePath: string, options?: {
+    maxSize?: number;
+}): Promise<MediaFileResult>;
+//# sourceMappingURL=file-operations.d.ts.map

package/dist/lib/file-operations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-operations.d.ts","sourceRoot":"","sources":["../../src/lib/file-operations.ts"],"names":[],"mappings":"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"}