@dollhousemcp/mcp-server
Version:
DollhouseMCP - A Model Context Protocol (MCP) server that enables dynamic AI persona management from markdown files, allowing Claude and other compatible AI assistants to activate and switch between different behavioral personas.
112 lines • 4.13 kB
TypeScript
/**
* ElementFileOperations - Common file operations for element managers
*
* Provides shared file handling operations for all element types:
* - Reading files with frontmatter parsing
* - Writing files with atomic operations
* - Directory scanning and filtering
*
* SECURITY: All operations use FileLockManager for atomic reads/writes
* PATH VALIDATION: All paths are validated before file operations
* LOGGING: Operations are logged for debugging and audit trail
*/
import { FileLockManager } from '../../security/fileLockManager.js';
/**
* Result of parsing a file with frontmatter
*/
export interface ParsedFile {
metadata: any;
content: string;
raw: string;
}
/**
* Options for file operations
*/
export interface FileOperationOptions {
/** Maximum file size in bytes (default: 1MB) */
maxSize?: number;
/** Whether to validate path is within base directory (default: true) */
validatePath?: boolean;
/** Whether to create directory if it doesn't exist (default: true) */
ensureDir?: boolean;
}
/**
* Utility class for common file operations
* Used by BaseElementManager and can be used by other managers
*
* DEPENDENCY INJECTION: Requires FileLockManager instance for atomic operations
*/
export declare class ElementFileOperations {
private fileLockManager;
/**
* Constructor - accepts FileLockManager for atomic operations
* @param fileLockManager - FileLockManager instance for atomic file operations
*/
constructor(fileLockManager: FileLockManager);
/**
* Atomically read a file with frontmatter
* SECURITY: Uses FileLockManager to prevent race conditions
*
* @param filePath - Absolute or relative path to file
* @param baseDir - Base directory for validation
* @param options - Operation options
* @returns Parsed file with metadata and content
*/
readFileWithFrontmatter(filePath: string, baseDir: string, options?: FileOperationOptions): Promise<ParsedFile>;
/**
* Atomically write a file with frontmatter
* SECURITY: Uses FileLockManager to prevent corruption
*
* @param filePath - Absolute or relative path to file
* @param metadata - YAML frontmatter metadata
* @param content - File content
* @param baseDir - Base directory for validation
* @param options - Operation options
*/
writeFileWithFrontmatter(filePath: string, metadata: any, content: string, baseDir: string, options?: FileOperationOptions): Promise<void>;
/**
* Validate path is within base directory and resolve to absolute path
* SECURITY: Prevents path traversal attacks
*
* @param filePath - Path to validate
* @param baseDir - Base directory
* @returns Normalized absolute path
* @throws Error if path is invalid or outside base directory
*/
validateAndResolvePath(filePath: string, baseDir: string): string;
/**
* Generate filename from element name
* Converts name to lowercase and replaces invalid characters with hyphens
*
* @param name - Element name
* @param extension - File extension (default: '.md')
* @returns Sanitized filename
*/
generateFilename(name: string, extension?: string): string;
/**
* Check if a file exists
*
* @param filePath - Path to check
* @param baseDir - Base directory (optional)
* @returns True if file exists
*/
fileExists(filePath: string, baseDir?: string): Promise<boolean>;
/**
* Delete a file with validation
* SECURITY: Validates path before deletion
*
* @param filePath - Path to delete
* @param baseDir - Base directory for validation
* @throws Error if path is invalid
*/
deleteFile(filePath: string, baseDir: string): Promise<void>;
/**
* List files in a directory
*
* @param dir - Directory to list
* @param extension - Filter by extension (optional)
* @returns Array of file paths
*/
listFiles(dir: string, extension?: string): Promise<string[]>;
}
//# sourceMappingURL=ElementFileOperations.d.ts.map