image-processor-mcp 0.1.0

package/build/controllers/tool.controller.js

@@ -0,0 +1,230 @@
+import fs from 'fs-extra';
+import axios from 'axios';
+import path from 'path';
+import { FileService } from '../services/file.services.js';
+import { ImageService } from '../services/image.services.js';
+import { ReportService } from '../services/report.services.js';
+import { DEFAULTS, CONFIG_DESCRIPTIONS, SUPPORTED_EXTENSIONS, INPUT_EXTENSION_DESCRIPTIONS, SUPPORTED_OUTPUT_FORMATS, OUTPUT_FORMAT_DESCRIPTIONS, } from '../config/config.constants.js';
+import { APP_CONFIG } from '../config/app.config.js';
+export class ToolController {
+    static async handleDownloadImage(args) {
+        try {
+            await fs.ensureDir(path.dirname(args.outputPath));
+            const response = await axios({
+                method: 'GET',
+                url: args.url,
+                responseType: 'arraybuffer',
+                headers: {
+                    'User-Agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36',
+                },
+                timeout: 30000,
+            });
+            await fs.writeFile(args.outputPath, response.data);
+            return {
+                content: [{ type: 'text', text: `Successfully downloaded image to ${args.outputPath}` }],
+            };
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : 'Unknown error occurred';
+            console.error('Download error:', errorMessage);
+            return { content: [{ type: 'text', text: `Failed to download image: ${errorMessage}` }], isError: true };
+        }
+    }
+    static async handleCompressImage(args) {
+        try {
+            await FileService.ensureDir(path.dirname(args.outputPath));
+            const result = await ImageService.compressImage(args.inputPath, args.outputPath, {
+                quality: args.quality,
+                lossless: args.lossless,
+                effort: args.effort,
+                width: args.width,
+                height: args.height,
+                maxDimension: args.maxDimension,
+                recursiveCompress: args.recursiveCompress,
+                expectedSizeKB: args.expectedSizeKB,
+                qualityStepDown: args.qualityStepDown,
+                minimumQualityFloor: args.minimumQualityFloor,
+                outputFormat: args.outputFormat,
+            });
+            if (!result.success) {
+                return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }], isError: true };
+            }
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : 'Unknown error occurred';
+            return { content: [{ type: 'text', text: `Failed to compress image: ${errorMessage}` }], isError: true };
+        }
+    }
+    static async handleCompressDirectory(args) {
+        const inputDir = path.resolve(args.inputDir);
+        const outputDir = path.resolve(args.outputDir);
+        const dirExists = await fs.pathExists(inputDir);
+        if (!dirExists) {
+            return { content: [{ type: 'text', text: `Input directory does not exist: ${inputDir}` }], isError: true };
+        }
+        await FileService.ensureDir(outputDir);
+        const outputFormat = args.outputFormat || DEFAULTS.outputFormat;
+        const quality = args.quality ?? DEFAULTS.quality;
+        const lossless = args.lossless ?? DEFAULTS.lossless;
+        const effort = args.effort ?? DEFAULTS.effort;
+        const maxDimension = args.maxDimension ?? DEFAULTS.maxDimension;
+        const recursiveCompress = args.recursiveCompress ?? false;
+        const expectedSizeKB = args.expectedSizeKB ?? DEFAULTS.expectedSizeKB;
+        const qualityStepDown = args.qualityStepDown ?? DEFAULTS.qualityStepDown;
+        const minimumQualityFloor = args.minimumQualityFloor ?? DEFAULTS.minimumQualityFloor;
+        const fileNaming = {
+            enabled: args.normalizeFilename ?? false,
+            replaceChars: args.filenameReplaceChars
+                ? args.filenameReplaceChars.split(',').map(c => c.trim()).filter(c => c)
+                : DEFAULTS.filenameReplaceChars,
+            case: args.filenameCase || DEFAULTS.filenameCase,
+        };
+        const dirNaming = {
+            enabled: args.normalizeDirname ?? false,
+            replaceChars: args.dirnameReplaceChars
+                ? args.dirnameReplaceChars.split(',').map(c => c.trim()).filter(c => c)
+                : DEFAULTS.dirnameReplaceChars,
+            case: args.dirnameCase || DEFAULTS.dirnameCase,
+        };
+        try {
+            const startTime = Date.now();
+            const allImageFiles = await FileService.getImageFiles(inputDir);
+            const toProcess = [];
+            const skipped = [];
+            for (const f of allImageFiles) {
+                if (path.extname(f).toLowerCase() === '.' + outputFormat) {
+                    skipped.push(f);
+                }
+                else {
+                    toProcess.push(f);
+                }
+            }
+            const results = [];
+            for (const inputPath of toProcess) {
+                const outputPath = FileService.getOutputPath(inputPath, inputDir, outputDir, outputFormat, fileNaming, dirNaming);
+                await FileService.ensureDir(path.dirname(outputPath));
+                const result = await ImageService.compressImage(inputPath, outputPath, {
+                    quality,
+                    lossless,
+                    effort,
+                    maxDimension,
+                    recursiveCompress,
+                    expectedSizeKB,
+                    qualityStepDown,
+                    minimumQualityFloor,
+                    outputFormat,
+                });
+                results.push(result);
+            }
+            const duration = Date.now() - startTime;
+            const reportPath = await ReportService.generateReport(results, inputDir, outputDir, outputFormat, startTime, duration, skipped);
+            const successful = results.filter(r => r.success).length;
+            const failed = results.length - successful;
+            const totalOriginal = results.reduce((s, r) => s + r.originalSize, 0);
+            const totalCompressed = results.reduce((s, r) => s + r.compressedSize, 0);
+            const overallReduction = totalOriginal > 0
+                ? parseFloat(((totalOriginal - totalCompressed) / totalOriginal * 100).toFixed(2))
+                : 0;
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: true,
+                            totalFiles: results.length,
+                            successful,
+                            failed,
+                            totalOriginalSize: totalOriginal,
+                            totalCompressedSize: totalCompressed,
+                            overallReduction,
+                            durationMs: duration,
+                            reportPath,
+                        }, null, 2),
+                    }],
+            };
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : 'Unknown error occurred';
+            return { content: [{ type: 'text', text: `Failed to process directory: ${errorMessage}` }], isError: true };
+        }
+    }
+    static handleGetAcknowledgement() {
+        const inputExtensions = SUPPORTED_EXTENSIONS.map(ext => ({
+            ext,
+            description: INPUT_EXTENSION_DESCRIPTIONS[ext] || 'Image format',
+        }));
+        const outputFormats = SUPPORTED_OUTPUT_FORMATS.map(format => ({
+            format,
+            description: OUTPUT_FORMAT_DESCRIPTIONS[format] || 'Output format',
+        }));
+        const tools = [
+            {
+                name: 'download_image',
+                description: 'Download an image from a URL to a specified path',
+                parameters: [
+                    { name: 'url', type: 'string', required: true, description: 'URL of the image to download' },
+                    { name: 'outputPath', type: 'string', required: true, description: 'Local path where to save the downloaded image' },
+                ],
+            },
+            {
+                name: 'compress_image',
+                description: 'Compress or convert a single image with format conversion, quality adjustment, resizing, and optional recursive compression',
+                parameters: [
+                    { name: 'inputPath', type: 'string', required: true, description: 'Path to the input image' },
+                    { name: 'outputPath', type: 'string', required: true, description: 'Path where to save the compressed image' },
+                    { name: 'outputFormat', type: 'string', required: false, default: DEFAULTS.outputFormat, description: 'Output image format. Supported: ' + SUPPORTED_OUTPUT_FORMATS.join(', ') },
+                    { name: 'quality', type: 'number', required: false, default: DEFAULTS.quality, description: 'Compression quality (1-100). Higher = better quality, larger file.' },
+                    { name: 'lossless', type: 'boolean', required: false, default: DEFAULTS.lossless, description: 'Use lossless compression. Preserves all pixel data.' },
+                    { name: 'effort', type: 'number', required: false, default: DEFAULTS.effort, description: 'CPU effort (0-6). Higher = better compression, slower.' },
+                    { name: 'width', type: 'number', required: false, description: 'Exact target width in pixels. Aspect ratio maintained if only width specified.' },
+                    { name: 'height', type: 'number', required: false, description: 'Exact target height in pixels. Aspect ratio maintained if only height specified.' },
+                    { name: 'maxDimension', type: 'number', required: false, default: DEFAULTS.maxDimension, description: 'Auto-resize if width or height exceeds this pixel threshold.' },
+                    { name: 'recursiveCompress', type: 'boolean', required: false, default: false, description: 'Re-compress until file size is under expectedSizeKB.' },
+                    { name: 'expectedSizeKB', type: 'number', required: false, default: DEFAULTS.expectedSizeKB, description: 'Target file size in KB for recursive compression.' },
+                    { name: 'qualityStepDown', type: 'number', required: false, default: DEFAULTS.qualityStepDown, description: 'Quality reduction per recursive iteration.' },
+                    { name: 'minimumQualityFloor', type: 'number', required: false, default: DEFAULTS.minimumQualityFloor, description: 'Minimum quality allowed during recursive compression.' },
+                ],
+            },
+            {
+                name: 'compress_directory',
+                description: 'Batch compress all images in a directory recursively, preserving folder structure, with auto-generated report',
+                parameters: [
+                    { name: 'inputDir', type: 'string', required: true, description: 'Input directory containing images to compress' },
+                    { name: 'outputDir', type: 'string', required: true, description: 'Output directory where compressed images will be saved' },
+                    { name: 'outputFormat', type: 'string', required: false, default: DEFAULTS.outputFormat, description: 'Output image format. Supported: ' + SUPPORTED_OUTPUT_FORMATS.join(', ') },
+                    { name: 'quality', type: 'number', required: false, default: DEFAULTS.quality, description: 'Compression quality (1-100)' },
+                    { name: 'lossless', type: 'boolean', required: false, default: DEFAULTS.lossless, description: 'Use lossless compression' },
+                    { name: 'effort', type: 'number', required: false, default: DEFAULTS.effort, description: 'CPU effort (0-6)' },
+                    { name: 'maxDimension', type: 'number', required: false, default: DEFAULTS.maxDimension, description: 'Auto-resize threshold in pixels' },
+                    { name: 'normalizeFilename', type: 'boolean', required: false, default: false, description: 'Enable filename normalization (replace chars, apply case)' },
+                    { name: 'filenameReplaceChars', type: 'string', required: false, description: 'Characters to replace with underscore, comma-separated' },
+                    { name: 'filenameCase', type: 'string', required: false, default: DEFAULTS.filenameCase, description: 'Filename case: lowercase, uppercase, or original' },
+                    { name: 'normalizeDirname', type: 'boolean', required: false, default: false, description: 'Enable directory name normalization' },
+                    { name: 'dirnameReplaceChars', type: 'string', required: false, description: 'Characters to replace in directory names, comma-separated' },
+                    { name: 'dirnameCase', type: 'string', required: false, default: DEFAULTS.dirnameCase, description: 'Directory name case: lowercase, uppercase, or original' },
+                    { name: 'recursiveCompress', type: 'boolean', required: false, default: false, description: 'Re-compress oversized outputs until target size' },
+                    { name: 'expectedSizeKB', type: 'number', required: false, default: DEFAULTS.expectedSizeKB, description: 'Target file size in KB' },
+                    { name: 'qualityStepDown', type: 'number', required: false, default: DEFAULTS.qualityStepDown, description: 'Quality decrease per iteration' },
+                    { name: 'minimumQualityFloor', type: 'number', required: false, default: DEFAULTS.minimumQualityFloor, description: 'Minimum quality floor' },
+                ],
+            },
+            {
+                name: 'get_acknowledgement',
+                description: 'Get all configuration defaults, supported formats, and detailed tool descriptions. Use this tool to understand the full capabilities of this MCP server.',
+                parameters: [],
+            },
+        ];
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify({
+                        app: { name: APP_CONFIG.name, version: APP_CONFIG.version },
+                        configDefaults: CONFIG_DESCRIPTIONS,
+                        supportedInputExtensions: inputExtensions,
+                        supportedOutputFormats: outputFormats,
+                        tools,
+                    }, null, 2),
+                }],
+        };
+    }
+}

package/build/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/build/index.js

@@ -0,0 +1,179 @@
+#!/usr/bin/env node
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ErrorCode, ListToolsRequestSchema, McpError, } from '@modelcontextprotocol/sdk/types.js';
+import sharp from 'sharp';
+import { ToolController } from './controllers/tool.controller.js';
+import { APP_CONFIG } from './config/app.config.js';
+sharp.cache(false);
+class ImageDownloaderServer {
+    constructor() {
+        this.server = new Server({
+            name: APP_CONFIG.name,
+            version: APP_CONFIG.version,
+        }, {
+            capabilities: {
+                tools: {},
+            },
+        });
+        this.setupToolHandlers();
+        this.server.onerror = (error) => console.error('[MCP Error]', error);
+        process.on('SIGINT', async () => {
+            await this.server.close();
+            process.exit(0);
+        });
+    }
+    isDownloadImageArgs(args) {
+        if (!args || typeof args !== 'object')
+            return false;
+        const a = args;
+        return typeof a.url === 'string' && typeof a.outputPath === 'string';
+    }
+    isCompressImageArgs(args) {
+        if (!args || typeof args !== 'object')
+            return false;
+        const a = args;
+        return (typeof a.inputPath === 'string' &&
+            typeof a.outputPath === 'string' &&
+            (a.outputFormat === undefined || typeof a.outputFormat === 'string') &&
+            (a.quality === undefined || typeof a.quality === 'number') &&
+            (a.lossless === undefined || typeof a.lossless === 'boolean') &&
+            (a.effort === undefined || typeof a.effort === 'number') &&
+            (a.width === undefined || typeof a.width === 'number') &&
+            (a.height === undefined || typeof a.height === 'number') &&
+            (a.maxDimension === undefined || typeof a.maxDimension === 'number') &&
+            (a.recursiveCompress === undefined || typeof a.recursiveCompress === 'boolean') &&
+            (a.expectedSizeKB === undefined || typeof a.expectedSizeKB === 'number') &&
+            (a.qualityStepDown === undefined || typeof a.qualityStepDown === 'number') &&
+            (a.minimumQualityFloor === undefined || typeof a.minimumQualityFloor === 'number'));
+    }
+    isCompressDirectoryArgs(args) {
+        if (!args || typeof args !== 'object')
+            return false;
+        const a = args;
+        return (typeof a.inputDir === 'string' &&
+            typeof a.outputDir === 'string' &&
+            (a.outputFormat === undefined || typeof a.outputFormat === 'string') &&
+            (a.quality === undefined || typeof a.quality === 'number') &&
+            (a.lossless === undefined || typeof a.lossless === 'boolean') &&
+            (a.effort === undefined || typeof a.effort === 'number') &&
+            (a.maxDimension === undefined || typeof a.maxDimension === 'number') &&
+            (a.normalizeFilename === undefined || typeof a.normalizeFilename === 'boolean') &&
+            (a.filenameReplaceChars === undefined || typeof a.filenameReplaceChars === 'string') &&
+            (a.filenameCase === undefined || typeof a.filenameCase === 'string') &&
+            (a.normalizeDirname === undefined || typeof a.normalizeDirname === 'boolean') &&
+            (a.dirnameReplaceChars === undefined || typeof a.dirnameReplaceChars === 'string') &&
+            (a.dirnameCase === undefined || typeof a.dirnameCase === 'string') &&
+            (a.recursiveCompress === undefined || typeof a.recursiveCompress === 'boolean') &&
+            (a.expectedSizeKB === undefined || typeof a.expectedSizeKB === 'number') &&
+            (a.qualityStepDown === undefined || typeof a.qualityStepDown === 'number') &&
+            (a.minimumQualityFloor === undefined || typeof a.minimumQualityFloor === 'number'));
+    }
+    setupToolHandlers() {
+        this.server.setRequestHandler(ListToolsRequestSchema, async () => ({
+            tools: [
+                {
+                    name: 'download_image',
+                    description: 'Download an image from a URL to a specified path',
+                    inputSchema: {
+                        type: 'object',
+                        properties: {
+                            url: { type: 'string', description: 'URL of the image to download' },
+                            outputPath: { type: 'string', description: 'Path where to save the image' },
+                        },
+                        required: ['url', 'outputPath'],
+                    },
+                },
+                {
+                    name: 'compress_image',
+                    description: 'Compress or convert a single image with format conversion, quality adjustment, resizing, and optional recursive compression',
+                    inputSchema: {
+                        type: 'object',
+                        properties: {
+                            inputPath: { type: 'string', description: 'Path to the input image' },
+                            outputPath: { type: 'string', description: 'Path where to save the compressed image' },
+                            outputFormat: { type: 'string', description: 'Output format: webp, avif, jpeg, png, tiff, gif (default: webp)' },
+                            quality: { type: 'number', description: 'Compression quality 1-100 (default: 85)', minimum: 1, maximum: 100 },
+                            lossless: { type: 'boolean', description: 'Use lossless compression (default: false)' },
+                            effort: { type: 'number', description: 'CPU effort 0-6, 6 is slowest with best compression (default: 6)', minimum: 0, maximum: 6 },
+                            width: { type: 'number', description: 'Exact target width (maintains aspect ratio if only width is specified)' },
+                            height: { type: 'number', description: 'Exact target height (maintains aspect ratio if only height is specified)' },
+                            maxDimension: { type: 'number', description: 'Auto-resize if width or height exceeds this threshold (default: 2000)' },
+                            recursiveCompress: { type: 'boolean', description: 'Re-compress until file is under target size (default: false)' },
+                            expectedSizeKB: { type: 'number', description: 'Target file size in KB for recursive compression (default: 100)' },
+                            qualityStepDown: { type: 'number', description: 'Quality decrease per recursive iteration (default: 5)' },
+                            minimumQualityFloor: { type: 'number', description: 'Minimum quality allowed during recursive compression (default: 10)' },
+                        },
+                        required: ['inputPath', 'outputPath'],
+                    },
+                },
+                {
+                    name: 'compress_directory',
+                    description: 'Batch compress all images in a directory recursively, preserving folder structure, with an auto-generated report',
+                    inputSchema: {
+                        type: 'object',
+                        properties: {
+                            inputDir: { type: 'string', description: 'Input directory containing images' },
+                            outputDir: { type: 'string', description: 'Output directory for compressed images' },
+                            outputFormat: { type: 'string', description: 'Output format: webp, avif, jpeg, png, tiff, gif (default: webp)' },
+                            quality: { type: 'number', description: 'Compression quality 1-100 (default: 85)', minimum: 1, maximum: 100 },
+                            lossless: { type: 'boolean', description: 'Use lossless compression (default: false)' },
+                            effort: { type: 'number', description: 'CPU effort 0-6 (default: 6)', minimum: 0, maximum: 6 },
+                            maxDimension: { type: 'number', description: 'Auto-resize threshold in pixels (default: 2000)' },
+                            normalizeFilename: { type: 'boolean', description: 'Enable filename normalization' },
+                            filenameReplaceChars: { type: 'string', description: 'Characters to replace with underscore, comma-separated' },
+                            filenameCase: { type: 'string', description: 'Filename case: lowercase, uppercase, original' },
+                            normalizeDirname: { type: 'boolean', description: 'Enable directory name normalization' },
+                            dirnameReplaceChars: { type: 'string', description: 'Characters to replace in directory names, comma-separated' },
+                            dirnameCase: { type: 'string', description: 'Directory name case: lowercase, uppercase, original' },
+                            recursiveCompress: { type: 'boolean', description: 'Re-compress oversized outputs until target size' },
+                            expectedSizeKB: { type: 'number', description: 'Target file size in KB (default: 100)' },
+                            qualityStepDown: { type: 'number', description: 'Quality decrease per iteration (default: 5)' },
+                            minimumQualityFloor: { type: 'number', description: 'Minimum quality floor (default: 10)' },
+                        },
+                        required: ['inputDir', 'outputDir'],
+                    },
+                },
+                {
+                    name: 'get_acknowledgement',
+                    description: 'Get all configuration defaults, supported formats, and detailed tool descriptions with parameter explanations',
+                    inputSchema: {
+                        type: 'object',
+                        properties: {},
+                        required: [],
+                    },
+                },
+            ],
+        }));
+        this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
+            switch (request.params.name) {
+                case 'download_image':
+                    if (!this.isDownloadImageArgs(request.params.arguments)) {
+                        throw new McpError(ErrorCode.InvalidParams, 'Invalid arguments for download_image');
+                    }
+                    return ToolController.handleDownloadImage(request.params.arguments);
+                case 'compress_image':
+                    if (!this.isCompressImageArgs(request.params.arguments)) {
+                        throw new McpError(ErrorCode.InvalidParams, 'Invalid arguments for compress_image');
+                    }
+                    return ToolController.handleCompressImage(request.params.arguments);
+                case 'compress_directory':
+                    if (!this.isCompressDirectoryArgs(request.params.arguments)) {
+                        throw new McpError(ErrorCode.InvalidParams, 'Invalid arguments for compress_directory');
+                    }
+                    return ToolController.handleCompressDirectory(request.params.arguments);
+                case 'get_acknowledgement':
+                    return ToolController.handleGetAcknowledgement();
+                default:
+                    throw new McpError(ErrorCode.MethodNotFound, "Unknown tool: " + request.params.name);
+            }
+        });
+    }
+    async run() {
+        const transport = new StdioServerTransport();
+        await this.server.connect(transport);
+        console.error('Image Downloader MCP server running on stdio');
+    }
+}
+const server = new ImageDownloaderServer();
+server.run().catch(console.error);

package/build/services/file.services.d.ts

@@ -0,0 +1,17 @@
+import type { FileNamingOptions, ScanFile, TreeNode } from '../types.js';
+export declare class FileService {
+    static getImageFiles(dirPath: string, extensions?: string[]): Promise<string[]>;
+    static getFileSize(filePath: string): Promise<number>;
+    static ensureDir(dirPath: string): Promise<void>;
+    static normalizeName(name: string, options: {
+        replaceChars: string[];
+        case: string;
+    }): string;
+    static getOutputPath(inputPath: string, inputDir: string, outputDir: string, format: string, fileNaming: FileNamingOptions, dirNaming: FileNamingOptions): string;
+    static scanFiles(dirPath: string, baseDir: string, extensions: string[]): Promise<ScanFile[]>;
+    static buildTree(files: ScanFile[], baseDir: string): TreeNode;
+    private static sortTree;
+    static formatTreeMarkdown(node: TreeNode, indent?: string): string[];
+    static normalizeKey(str: string): string;
+    static formatBytes(bytes: number): string;
+}

package/build/services/file.services.js

@@ -0,0 +1,170 @@
+import fs from 'fs-extra';
+import path from 'path';
+import { SUPPORTED_EXTENSIONS } from '../config/config.constants.js';
+export class FileService {
+    static async getImageFiles(dirPath, extensions = SUPPORTED_EXTENSIONS) {
+        const files = [];
+        const items = await fs.readdir(dirPath, { withFileTypes: true });
+        for (const item of items) {
+            const fullPath = path.join(dirPath, item.name);
+            if (item.isDirectory()) {
+                const subFiles = await this.getImageFiles(fullPath, extensions);
+                files.push(...subFiles);
+            }
+            else if (item.isFile()) {
+                const ext = path.extname(item.name).toLowerCase();
+                if (extensions.includes(ext)) {
+                    files.push(fullPath);
+                }
+            }
+        }
+        return files;
+    }
+    static async getFileSize(filePath) {
+        try {
+            const stats = await fs.stat(filePath);
+            return stats.size;
+        }
+        catch {
+            return 0;
+        }
+    }
+    static async ensureDir(dirPath) {
+        await fs.ensureDir(dirPath);
+    }
+    static normalizeName(name, options) {
+        let normalized = name;
+        if (options.replaceChars.length > 0) {
+            for (const char of options.replaceChars) {
+                if (char) {
+                    normalized = normalized.split(char).join('_');
+                }
+            }
+            normalized = normalized.replace(/_+/g, '_').replace(/^_|_$/g, '');
+        }
+        if (options.case === 'lowercase')
+            normalized = normalized.toLowerCase();
+        else if (options.case === 'uppercase')
+            normalized = normalized.toUpperCase();
+        return normalized;
+    }
+    static getOutputPath(inputPath, inputDir, outputDir, format, fileNaming, dirNaming) {
+        const relativePath = path.relative(inputDir, inputPath);
+        let normalizedPath = relativePath;
+        if (dirNaming.enabled) {
+            const parts = relativePath.split(path.sep);
+            const dirParts = parts.slice(0, -1).map(d => this.normalizeName(d, dirNaming));
+            const filename = parts[parts.length - 1];
+            normalizedPath = dirParts.length > 0 ? path.join(...dirParts, filename) : filename;
+        }
+        if (fileNaming.enabled) {
+            const ext = path.extname(normalizedPath);
+            const name = path.basename(normalizedPath, ext);
+            const dir = path.dirname(normalizedPath);
+            const normalizedName = this.normalizeName(name, fileNaming);
+            normalizedPath = dir === '.' ? `${normalizedName}${ext}` : path.join(dir, `${normalizedName}${ext}`);
+        }
+        const baseName = path.basename(normalizedPath, path.extname(normalizedPath));
+        const dir = path.dirname(normalizedPath);
+        const newExt = `.${format}`;
+        const outputRelPath = dir === '.' ? `${baseName}${newExt}` : path.join(dir, `${baseName}${newExt}`);
+        return path.join(outputDir, outputRelPath);
+    }
+    static async scanFiles(dirPath, baseDir, extensions) {
+        const files = [];
+        const items = await fs.readdir(dirPath, { withFileTypes: true });
+        for (const item of items) {
+            const fullPath = path.join(dirPath, item.name);
+            if (item.isDirectory()) {
+                const subFiles = await this.scanFiles(fullPath, baseDir, extensions);
+                files.push(...subFiles);
+            }
+            else if (item.isFile()) {
+                const ext = path.extname(item.name).toLowerCase();
+                if (extensions.includes(ext)) {
+                    const stats = await fs.stat(fullPath);
+                    files.push({
+                        fullPath,
+                        relativePath: path.relative(baseDir, fullPath),
+                        size: stats.size,
+                        ext,
+                        nameWithoutExt: path.basename(item.name, path.extname(item.name)),
+                    });
+                }
+            }
+        }
+        return files;
+    }
+    static buildTree(files, baseDir) {
+        const root = { name: path.basename(path.resolve(baseDir)), type: 'directory', children: [] };
+        for (const file of files) {
+            const parts = file.relativePath.split(path.sep);
+            let current = root;
+            for (let i = 0; i < parts.length; i++) {
+                const part = parts[i];
+                const isLast = i === parts.length - 1;
+                let child = current.children?.find(c => c.name === part);
+                if (!child) {
+                    child = {
+                        name: part,
+                        type: isLast ? 'file' : 'directory',
+                        children: isLast ? undefined : [],
+                        size: isLast ? file.size : undefined,
+                    };
+                    current.children.push(child);
+                }
+                current = child;
+            }
+        }
+        this.sortTree(root);
+        return root;
+    }
+    static sortTree(node) {
+        if (!node.children)
+            return;
+        node.children.sort((a, b) => {
+            if (a.type !== b.type)
+                return a.type === 'directory' ? -1 : 1;
+            return a.name.localeCompare(b.name);
+        });
+        for (const child of node.children) {
+            this.sortTree(child);
+        }
+    }
+    static formatTreeMarkdown(node, indent = '') {
+        const lines = [];
+        if (indent === '') {
+            lines.push('.');
+        }
+        if (!node.children)
+            return lines;
+        for (let i = 0; i < node.children.length; i++) {
+            const child = node.children[i];
+            const isLast = i === node.children.length - 1;
+            const connector = isLast ? '`-- ' : '|-- ';
+            if (child.type === 'file') {
+                const sizeStr = this.formatBytes(child.size || 0);
+                lines.push(`${indent}${connector}${child.name} (${sizeStr})`);
+            }
+            else {
+                lines.push(`${indent}${connector}${child.name}`);
+                const newIndent = indent + (isLast ? '    ' : '|   ');
+                if (child.children) {
+                    lines.push(...this.formatTreeMarkdown(child, newIndent));
+                }
+            }
+        }
+        return lines;
+    }
+    static normalizeKey(str) {
+        return str.toLowerCase().replace(/[-\s.]+/g, '_');
+    }
+    static formatBytes(bytes) {
+        if (bytes === 0)
+            return '0 Bytes';
+        const k = 1024;
+        const sizes = ['Bytes', 'KB', 'MB', 'GB'];
+        const i = Math.floor(Math.log(bytes) / Math.log(k));
+        return parseFloat((bytes / Math.pow(k, i)).toFixed(2)) + ' ' + sizes[i];
+    }
+}

package/build/services/image.services.d.ts

@@ -0,0 +1,10 @@
+import sharp from 'sharp';
+import type { CompressionResult, CompressOptions } from '../types.js';
+export declare class ImageService {
+    static compressImage(inputPath: string, outputPath: string, options: CompressOptions): Promise<CompressionResult>;
+    static applyFormat(pipeline: sharp.Sharp, format: string, options: {
+        quality: number;
+        lossless: boolean;
+        effort: number;
+    }): sharp.Sharp;
+}