@dollhousemcp/mcp-server/dist/utils/ElementFormatter.d.ts

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.

/**
 * Element Formatter/Cleaner Tool
 *
 * Fixes common issues with malformed DollhouseMCP elements:
 * - Escaped newlines (\n instead of actual line breaks)
 * - Malformed metadata (embedded in content instead of top-level)
 * - Broken YAML structure
 * - Makes elements human-readable and editable
 *
 * FIXES IMPLEMENTED (Issue #1190):
 * 1. CRITICAL: Unescapes newline characters for readability
 * 2. HIGH: Extracts embedded metadata to proper YAML structure
 * 3. ENHANCEMENT: Formats YAML for consistency and readability
 */
import { ElementType } from '../portfolio/types.js';
import { IFileOperationsService } from '../services/FileOperationsService.js';
export interface ElementFormatterOptions {
    /** Whether to create backup files before formatting */
    backup?: boolean;
    /** Whether to fix files in place or create new files */
    inPlace?: boolean;
    /** Whether to validate YAML after formatting */
    validate?: boolean;
    /** Custom output directory for formatted files */
    outputDir?: string;
    /** Maximum file size to process (bytes) */
    maxFileSize?: number;
}
export interface FormatterResult {
    success: boolean;
    filePath: string;
    issues: string[];
    fixed: string[];
    error?: string;
    backupPath?: string;
}
export declare class ElementFormatter {
    private readonly options;
    private readonly fileOperations;
    constructor(options: ElementFormatterOptions | undefined, fileOperations: IFileOperationsService);
    /**
     * Normalize Unicode in user input
     *
     * FIX: MEDIUM PRIORITY - Normalizes Unicode to prevent homograph attacks
     */
    private normalizeUnicode;
    /**
     * Format a single element file
     * Refactored to reduce cognitive complexity by extracting methods
     */
    formatFile(filePath: string): Promise<FormatterResult>;
    /**
     * Validate file size
     */
    private validateFileSize;
    /**
     * Read and normalize file content
     */
    private readAndNormalizeFile;
    /**
     * Format content based on element type
     */
    private formatContent;
    /**
     * Validate formatted content if validation is enabled
     */
    private validateFormattedContent;
    /**
     * Create backup if requested
     */
    private createBackupIfNeeded;
    /**
     * Write formatted content to file
     */
    private writeFormattedFile;
    /**
     * Handle formatting errors
     */
    private handleFormatError;
    /**
     * Format multiple files
     *
     * FIX: Added parallel processing with concurrency limit for better performance
     */
    formatFiles(filePaths: string[], concurrencyLimit?: number): Promise<FormatterResult[]>;
    /**
     * Format all elements of a specific type
     */
    formatElementType(elementType: ElementType, portfolioDir: string): Promise<FormatterResult[]>;
    /**
     * Format memory elements in date folder structure
     */
    private formatMemoryDirectory;
    /**
     * Format standard elements (.md files)
     */
    private formatStandardDirectory;
    /**
     * Format a memory YAML file
     * Refactored to reduce cognitive complexity
     */
    private formatMemory;
    /**
     * Parse memory content using SecureYamlParser
     */
    private parseMemoryContent;
    /**
     * Process memory entries to fix issues
     */
    private processMemoryEntries;
    /**
     * Check if content has embedded metadata
     */
    private hasEmbeddedMetadata;
    /**
     * Handle embedded metadata extraction
     */
    private handleEmbeddedMetadata;
    /**
     * Unescape entry content
     */
    private unescapeEntryContent;
    /**
     * Ensure memory has proper structure
     * FIX (Issue #1211): Derive name from filename instead of auto-generated entry ID
     */
    private ensureMemoryStructure;
    /**
     * Format data as clean YAML
     * FIX: Improved YAML formatting for consistency and special character handling
     */
    private formatAsYaml;
    /**
     * Format a standard element (markdown with frontmatter)
     */
    private formatStandardElement;
    /**
     * Extract embedded metadata from content string
     *
     * FIX: Security hotspot - Replaced regex vulnerable to catastrophic backtracking
     * with a linear-time string parsing approach to prevent ReDoS attacks
     */
    private extractEmbeddedMetadata;
    /**
     * Unescape content (public static method - Issue #874)
     * Handles escaped newlines, tabs, and other escape sequences
     */
    static unescapeContent(text: string): string;
    /**
     * Unescape newline characters (private instance method)
     * Using replaceAll as per SonarCloud S7781
     * Using character map to avoid escape sequence issues
     */
    private unescapeNewlines;
    /**
     * Detect element type from file path
     * Enhanced with more explicit and robust path matching
     */
    private detectElementType;
    /**
     * Get output path for formatted file
     *
     * FIX: Added path traversal protection to prevent directory escape attacks
     */
    private getOutputPath;
}
//# sourceMappingURL=ElementFormatter.d.ts.map