@pellux/goodvibes-sdk 0.18.3 → 0.18.11

package/dist/platform/tools/read/file-readers.js

@@ -0,0 +1,365 @@
+import { readFileSync, statSync } from 'node:fs';
+import { extname } from 'node:path';
+import { resolveAndValidatePath } from '../../utils/path-safety.js';
+import { logger } from '../../utils/logger.js';
+import { isNotebookFile } from '../../utils/notebook.js';
+import { FileStateCache } from '../../state/file-cache.js';
+import { ProjectIndex } from '../../state/project-index.js';
+import { CodeIntelligence } from '../../intelligence/facade.js';
+import { IMAGE_SIZE_LIMIT, RESIZE_TARGETS, isImageFile as isImageFileByExt, isArchiveFile, getImageMediaType, validateMagicBytes, getImageMetadata, isBinaryByContent, humanSize, resizeImage, convertToPortableFormat, listArchiveContents, } from './media.js';
+import { formatContent, extractOutline, extractSymbols, extractAst } from './text.js';
+import { summarizeError } from '../../utils/error-display.js';
+function isPdfFile(ext) {
+    return ext.toLowerCase() === '.pdf';
+}
+function extractPdfText(body, pages) {
+    const texts = [];
+    const streamRe = /stream\r?\n([\s\S]*?)\r?\nendstream/g;
+    let m;
+    while ((m = streamRe.exec(body)) !== null) {
+        const chunk = m[1];
+        const parenRe = /\(([^)\\]*(?:\\.[^)\\]*)*)\)/g;
+        let pm;
+        while ((pm = parenRe.exec(chunk)) !== null) {
+            const text = pm[1]
+                .replace(/\\n/g, '\n')
+                .replace(/\\r/g, '\r')
+                .replace(/\\t/g, '\t')
+                .replace(/\\\\/g, '\\')
+                .replace(/\\\(/g, '(')
+                .replace(/\\\)/g, ')')
+                .trim();
+            if (text.length > 1)
+                texts.push(text);
+        }
+    }
+    if (texts.length === 0) {
+        return JSON.stringify({
+            note: 'PDF text extraction requires a dedicated library for complex PDFs. No readable text streams found.',
+            byteSize: Buffer.byteLength(body, 'utf-8'),
+            pages: pages ?? 'all',
+        });
+    }
+    const joined = texts.join(' ');
+    if (pages)
+        return `[pages: ${pages}]\n${joined}`;
+    return joined;
+}
+function formatNotebook(raw) {
+    let nb;
+    try {
+        nb = JSON.parse(raw);
+    }
+    catch {
+        return `[error: invalid notebook JSON]`;
+    }
+    if (!Array.isArray(nb.cells)) {
+        return '[error: notebook has no cells array]';
+    }
+    const parts = [];
+    nb.cells.forEach((cell, idx) => {
+        const cellType = cell.cell_type ?? 'unknown';
+        const source = Array.isArray(cell.source) ? cell.source.join('') : (cell.source ?? '');
+        parts.push(`[cell ${idx + 1}] (${cellType}):`);
+        parts.push(source);
+        if (cellType === 'code' && Array.isArray(cell.outputs) && cell.outputs.length > 0) {
+            const outputLines = [];
+            for (const out of cell.outputs) {
+                const textData = out.data?.['text/plain'] ?? out.data?.['text/html'] ?? out.text;
+                if (textData) {
+                    const text = Array.isArray(textData) ? textData.join('') : String(textData);
+                    outputLines.push(text.trimEnd());
+                }
+            }
+            if (outputLines.length > 0) {
+                parts.push('[output]:');
+                parts.push(outputLines.join('\n'));
+            }
+        }
+    });
+    return parts.join('\n');
+}
+function createReadBaseResult(target, byteSize, tokenEstimate) {
+    return {
+        path: target.fileInput.path,
+        resolvedPath: target.resolvedPath,
+        lineCount: 0,
+        byteSize,
+        tokenEstimate,
+        extract: target.extract,
+    };
+}
+function createReadErrorResult(target, message, byteSize = 0) {
+    return {
+        ...createReadBaseResult(target, byteSize, 0),
+        error: message,
+    };
+}
+function shouldIncludeContent(format) {
+    return format !== 'count_only' && format !== 'minimal';
+}
+function getImageMode(fileInput, context) {
+    return fileInput.image_mode ?? context.globalImageMode ?? 'default';
+}
+async function readImageFile(target, context, imageMode, maxImageSize) {
+    let imgBuffer;
+    try {
+        imgBuffer = readFileSync(target.resolvedPath);
+    }
+    catch (err) {
+        const message = summarizeError(err);
+        return createReadErrorResult(target, `Cannot read image: ${message}`);
+    }
+    const byteSize = imgBuffer.length;
+    if (byteSize > maxImageSize) {
+        const meta = getImageMetadata(imgBuffer, extname(target.resolvedPath));
+        return {
+            ...createReadBaseResult(target, byteSize, 0),
+            image: true,
+            mediaType: getImageMediaType(extname(target.resolvedPath)) ?? 'application/octet-stream',
+            content: `Image exceeds size limit (${byteSize} bytes > ${maxImageSize} bytes). Use max_image_size to increase.`,
+            imageMetadata: { ...meta, mode: imageMode },
+        };
+    }
+    const magicResult = validateMagicBytes(imgBuffer, extname(target.resolvedPath));
+    if (!magicResult.valid) {
+        logger.debug('[read] image magic bytes mismatch', {
+            path: target.resolvedPath,
+            expected: extname(target.resolvedPath),
+            detected: magicResult.detectedType ?? 'unknown',
+        });
+    }
+    const rawMeta = getImageMetadata(imgBuffer, extname(target.resolvedPath));
+    if (!shouldIncludeContent(context.format)) {
+        context.projectIndex.upsertFile(target.resolvedPath, Math.ceil(byteSize / 4));
+        return {
+            ...createReadBaseResult(target, byteSize, Math.ceil(byteSize / 4)),
+            image: true,
+            mediaType: getImageMediaType(extname(target.resolvedPath)) ?? 'application/octet-stream',
+            imageMetadata: { ...rawMeta, mode: imageMode },
+        };
+    }
+    if (imageMode === 'metadata-only') {
+        context.projectIndex.upsertFile(target.resolvedPath, Math.ceil(byteSize / 4));
+        return {
+            ...createReadBaseResult(target, byteSize, 0),
+            image: true,
+            mediaType: getImageMediaType(extname(target.resolvedPath)) ?? 'application/octet-stream',
+            content: `Image: ${rawMeta.width ?? '?'}x${rawMeta.height ?? '?'} ${rawMeta.format}, ${humanSize(byteSize)}`,
+            imageMetadata: { ...rawMeta, mode: imageMode },
+        };
+    }
+    let processedBuffer = imgBuffer;
+    let mediaType = getImageMediaType(extname(target.resolvedPath)) ?? 'application/octet-stream';
+    let resized = false;
+    let converted = false;
+    let originalFormat;
+    const convertResult = await convertToPortableFormat(imgBuffer, extname(target.resolvedPath));
+    if (convertResult.converted) {
+        processedBuffer = convertResult.buffer;
+        mediaType = convertResult.mediaType;
+        converted = true;
+        originalFormat = convertResult.originalFormat;
+    }
+    const resizeTarget = RESIZE_TARGETS[imageMode];
+    if (resizeTarget !== null) {
+        const resizeResult = await resizeImage(processedBuffer, mediaType, resizeTarget);
+        if (resizeResult.resized) {
+            processedBuffer = resizeResult.buffer;
+            resized = true;
+            if (resizeResult.width)
+                rawMeta.width = resizeResult.width;
+            if (resizeResult.height)
+                rawMeta.height = resizeResult.height;
+        }
+    }
+    const b64 = processedBuffer.toString('base64');
+    const tokenEst = Math.ceil(processedBuffer.length / 4);
+    context.projectIndex.upsertFile(target.resolvedPath, tokenEst);
+    const desc = `Image: ${rawMeta.width ?? '?'}x${rawMeta.height ?? '?'} ${rawMeta.format}, ${humanSize(byteSize)}${resized ? ' (resized)' : ''}${converted ? ` (converted from ${originalFormat})` : ''}`;
+    return {
+        ...createReadBaseResult(target, byteSize, tokenEst),
+        content: desc,
+        image: true,
+        mediaType,
+        imageData: { base64: b64, mediaType },
+        imageMetadata: { ...rawMeta, resized, converted, originalFormat, mode: imageMode },
+    };
+}
+function readArchiveFile(target, context) {
+    let archiveBuffer;
+    try {
+        archiveBuffer = readFileSync(target.resolvedPath);
+    }
+    catch (err) {
+        const message = summarizeError(err);
+        return createReadErrorResult(target, `Cannot read archive: ${message}`);
+    }
+    const listing = listArchiveContents(target.resolvedPath, archiveBuffer, extname(target.resolvedPath));
+    const tokenEst = Math.ceil(listing.length / 4);
+    context.projectIndex.upsertFile(target.resolvedPath, tokenEst);
+    return { ...createReadBaseResult(target, archiveBuffer.length, tokenEst), content: listing, lineCount: listing.split('\n').length, archive: true };
+}
+function readPdfFile(target, context, fileInput) {
+    let pdfRaw;
+    let pdfByteSize = 0;
+    try {
+        const buf = readFileSync(target.resolvedPath);
+        pdfByteSize = buf.length;
+        pdfRaw = buf.toString('binary');
+    }
+    catch (err) {
+        const message = summarizeError(err);
+        return createReadErrorResult(target, `Cannot read PDF: ${message}`);
+    }
+    const pdfText = extractPdfText(pdfRaw, fileInput.pages);
+    const tokenEst = Math.ceil(pdfByteSize / 4);
+    context.projectIndex.upsertFile(target.resolvedPath, tokenEst);
+    const pdfLines = pdfText.split('\n');
+    return { ...createReadBaseResult(target, pdfByteSize, tokenEst), content: shouldIncludeContent(context.format) ? pdfText : undefined, lineCount: pdfLines.length };
+}
+function readNotebookFile(target, context) {
+    let nbRaw;
+    let nbByteSize = 0;
+    try {
+        nbRaw = readFileSync(target.resolvedPath, 'utf-8');
+        nbByteSize = Buffer.byteLength(nbRaw, 'utf-8');
+    }
+    catch (err) {
+        const message = summarizeError(err);
+        return createReadErrorResult(target, `Cannot read notebook: ${message}`);
+    }
+    const formatted = formatNotebook(nbRaw);
+    const tokenEst = Math.ceil(nbByteSize / 4);
+    context.projectIndex.upsertFile(target.resolvedPath, tokenEst);
+    const nbLines = formatted.split('\n');
+    return { ...createReadBaseResult(target, nbByteSize, tokenEst), content: shouldIncludeContent(context.format) ? formatted : undefined, lineCount: nbLines.length };
+}
+async function readTextFile(target, context, fileInput) {
+    let fullBuf;
+    try {
+        fullBuf = readFileSync(target.resolvedPath);
+    }
+    catch (err) {
+        const message = summarizeError(err);
+        logger.debug('read tool: file read failed', { path: target.resolvedPath, error: message });
+        return createReadErrorResult(target, `Cannot read file: ${message}`);
+    }
+    if (isBinaryByContent(fullBuf)) {
+        logger.debug('read tool: binary file skipped', { path: target.resolvedPath });
+        return { ...createReadBaseResult(target, fullBuf.length, 0), binary: true };
+    }
+    let rawContent;
+    try {
+        rawContent = fullBuf.toString('utf-8');
+    }
+    catch (err) {
+        const message = summarizeError(err);
+        logger.debug('read tool: utf-8 decode failed', { path: target.resolvedPath, error: message });
+        return createReadErrorResult(target, `Cannot decode file as UTF-8: ${message}`, fullBuf.length);
+    }
+    const cacheResult = fileInput.force ? { status: 'miss' } : context.fileCache.lookup(target.resolvedPath);
+    context.fileCache.update(target.resolvedPath, rawContent, { tool: 'read' });
+    const byteSize = Buffer.byteLength(rawContent, 'utf-8');
+    const tokenEstimate = Math.ceil(byteSize / 4);
+    context.projectIndex.upsertFile(target.resolvedPath, tokenEstimate);
+    const lines = rawContent.split('\n');
+    const lineCount = lines.length;
+    let extractedContent;
+    if (shouldIncludeContent(context.format)) {
+        switch (target.extract) {
+            case 'content':
+            case 'lines':
+                extractedContent = formatContent(lines, context.includeLineNumbers, fileInput.range, context.maxPerItem);
+                break;
+            case 'outline':
+                extractedContent = await extractOutline(target.resolvedPath, rawContent, lines, context.includeLineNumbers, context.codeIntelligence);
+                break;
+            case 'symbols':
+                extractedContent = await extractSymbols(target.resolvedPath, rawContent, lines, context.includeLineNumbers, context.codeIntelligence);
+                break;
+            case 'ast':
+                extractedContent = await extractAst(target.resolvedPath, rawContent, lines, context.includeLineNumbers, context.codeIntelligence);
+                break;
+            default:
+                extractedContent = formatContent(lines, context.includeLineNumbers, fileInput.range, context.maxPerItem);
+        }
+    }
+    const result = {
+        ...createReadBaseResult(target, byteSize, tokenEstimate),
+        content: extractedContent,
+        lineCount,
+        cache: { status: cacheResult.status },
+    };
+    if (context.format === 'verbose') {
+        result.metadata = { encoding: 'utf-8', sizeBytes: byteSize, cacheStatus: cacheResult.status };
+    }
+    return result;
+}
+export async function readOneFile(fileInput, globalExtract, format, includeLineNumbers, maxPerItem, fileCache, projectIndex, globalImageMode, globalMaxImageSize, codeIntelligence) {
+    const extract = fileInput.extract ?? globalExtract;
+    let resolvedPath;
+    try {
+        resolvedPath = resolveAndValidatePath(fileInput.path, projectIndex.baseDir);
+    }
+    catch (err) {
+        const message = summarizeError(err);
+        logger.debug('read tool: path validation failed', { path: fileInput.path, error: message });
+        return createReadErrorResult({ fileInput, resolvedPath: fileInput.path, extract }, message);
+    }
+    const target = { fileInput, resolvedPath, extract };
+    const context = {
+        format,
+        includeLineNumbers,
+        maxPerItem,
+        fileCache,
+        projectIndex,
+        globalImageMode,
+        maxImageSize: globalMaxImageSize ?? IMAGE_SIZE_LIMIT,
+        codeIntelligence,
+    };
+    const ext = extname(resolvedPath);
+    const imageMode = getImageMode(fileInput, context);
+    if (isImageFileByExt(ext))
+        return readImageFile(target, context, imageMode, context.maxImageSize);
+    if (isArchiveFile(ext))
+        return readArchiveFile(target, context);
+    if (isPdfFile(ext))
+        return readPdfFile(target, context, fileInput);
+    if (isNotebookFile(resolvedPath))
+        return readNotebookFile(target, context);
+    return readTextFile(target, context, fileInput);
+}
+export function paginateFiles(files, tokenBudget, projectRoot) {
+    const pages = [];
+    let currentPage = [];
+    let currentTokens = 0;
+    for (let i = 0; i < files.length; i++) {
+        let est = 0;
+        try {
+            const resolved = resolveAndValidatePath(files[i].path, projectRoot);
+            est = Math.ceil(statSync(resolved).size / 4);
+        }
+        catch {
+            est = 0;
+        }
+        if (est > tokenBudget && currentPage.length === 0) {
+            pages.push([i]);
+            currentPage = [];
+            currentTokens = 0;
+            continue;
+        }
+        if (currentTokens + est > tokenBudget && currentPage.length > 0) {
+            pages.push(currentPage);
+            currentPage = [i];
+            currentTokens = est;
+        }
+        else {
+            currentPage.push(i);
+            currentTokens += est;
+        }
+    }
+    if (currentPage.length > 0)
+        pages.push(currentPage);
+    return pages;
+}

package/dist/platform/tools/read/index.d.ts

@@ -0,0 +1,19 @@
+import type { Tool, ToolDefinition } from '../../types/tools.js';
+import { FileStateCache } from '../../state/file-cache.js';
+import { ProjectIndex } from '../../state/project-index.js';
+import { CodeIntelligence } from '../../intelligence/facade.js';
+export type { FileReadResult, ReadOutput } from './file-readers.js';
+export declare class ReadTool implements Tool {
+    readonly definition: ToolDefinition;
+    private readonly fileCache;
+    private readonly projectIndex;
+    private readonly codeIntelligence;
+    constructor(projectIndex: ProjectIndex, fileCache?: FileStateCache, codeIntelligence?: Pick<CodeIntelligence, 'getOutline' | 'getSymbols'>);
+    execute(args: Record<string, unknown>): Promise<{
+        success: boolean;
+        output?: string;
+        error?: string;
+    }>;
+    private _execute;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/platform/tools/read/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/platform/tools/read/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAGjE,OAAO,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAC3D,OAAO,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AAC5D,OAAO,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAUhE,YAAY,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEpE,qBAAa,QAAS,YAAW,IAAI;IACnC,QAAQ,CAAC,UAAU,EAAE,cAAc,CASjC;IAEF,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAiB;IAC3C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAe;IAC5C,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAsD;gBAGrF,YAAY,EAAE,YAAY,EAC1B,SAAS,CAAC,EAAE,cAAc,EAC1B,gBAAgB,CAAC,EAAE,IAAI,CAAC,gBAAgB,EAAE,YAAY,GAAG,YAAY,CAAC;IAOlE,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;YAa9F,QAAQ;CAuHvB"}

package/dist/platform/tools/read/index.js

@@ -0,0 +1,133 @@
+import { READ_TOOL_SCHEMA } from './schema.js';
+import { FileStateCache } from '../../state/file-cache.js';
+import { ProjectIndex } from '../../state/project-index.js';
+import { CodeIntelligence } from '../../intelligence/facade.js';
+import { logger } from '../../utils/logger.js';
+import { summarizeError } from '../../utils/error-display.js';
+import { paginateFiles, readOneFile, } from './file-readers.js';
+export class ReadTool {
+    definition = {
+        name: 'read',
+        description: 'Read one or more files from disk. Supports extract modes (content, outline, symbols, lines, ast)'
+            + ' for token-efficient reading, per-file caching, pagination via token_budget, and batch processing.',
+        parameters: READ_TOOL_SCHEMA,
+        sideEffects: ['read_fs'],
+        concurrency: 'parallel',
+        supportsProgress: true,
+    };
+    fileCache;
+    projectIndex;
+    codeIntelligence;
+    constructor(projectIndex, fileCache, codeIntelligence) {
+        this.fileCache = fileCache ?? new FileStateCache();
+        this.projectIndex = projectIndex;
+        this.codeIntelligence = codeIntelligence ?? new CodeIntelligence({});
+    }
+    async execute(args) {
+        if (!Array.isArray(args.files) || args.files.length === 0) {
+            return { success: false, error: 'Missing or empty "files" array' };
+        }
+        try {
+            return await this._execute(args);
+        }
+        catch (err) {
+            const message = summarizeError(err);
+            logger.error('read tool: unexpected error', { error: message });
+            return { success: false, error: `Unexpected error: ${message}` };
+        }
+    }
+    async _execute(input) {
+        const globalExtract = input.extract ?? 'content';
+        const format = input.output?.format ?? 'standard';
+        const includeLineNumbers = input.output?.include_line_numbers ?? true;
+        const maxPerItem = input.output?.max_per_item;
+        const maxTokens = input.output?.max_tokens;
+        const tokenBudget = input.token_budget;
+        const page = Math.max(1, input.page ?? 1);
+        const globalImageMode = input.image_mode;
+        const globalMaxImageSize = input.max_image_size;
+        const allFiles = input.files;
+        let filesToProcess = allFiles;
+        let paginationInfo;
+        if (tokenBudget !== undefined) {
+            const pages = paginateFiles(allFiles, tokenBudget, this.projectIndex.baseDir);
+            const totalPages = Math.max(1, pages.length);
+            const pageIdx = Math.min(page - 1, totalPages - 1);
+            const pageIndices = pages[pageIdx] ?? [];
+            filesToProcess = pageIndices.map((i) => allFiles[i]);
+            const deliveredSet = new Set(pages.slice(0, pageIdx + 1).flat());
+            const pendingFiles = allFiles
+                .map((f, i) => ({ f, i }))
+                .filter(({ i }) => !deliveredSet.has(i))
+                .map(({ f }) => f.path);
+            paginationInfo = { page, total_pages: totalPages, pending_files: pendingFiles };
+        }
+        const results = await Promise.all(filesToProcess.map((f) => readOneFile(f, globalExtract, format, includeLineNumbers, maxPerItem, this.fileCache, this.projectIndex, globalImageMode, globalMaxImageSize, this.codeIntelligence)));
+        if (maxTokens !== undefined) {
+            let usedTokens = 0;
+            for (const r of results) {
+                if (r.content === undefined)
+                    continue;
+                const contentTokens = Math.ceil(r.content.length / 4);
+                if (usedTokens + contentTokens > maxTokens) {
+                    const remaining = Math.max(0, maxTokens - usedTokens);
+                    r.content = r.content.slice(0, remaining * 4);
+                }
+                usedTokens += Math.ceil((r.content?.length ?? 0) / 4);
+            }
+        }
+        const images = [];
+        const fileResults = results.map((r) => {
+            if (r.imageData) {
+                images.push({
+                    path: r.path,
+                    base64: r.imageData.base64,
+                    mediaType: r.imageData.mediaType,
+                    description: r.content ?? `Image: ${r.path}`,
+                });
+                const { imageData: _imageData, ...rest } = r;
+                return rest;
+            }
+            return r;
+        });
+        const filesBinary = fileResults.filter((r) => r.binary === true).length;
+        const filesErrored = fileResults.filter((r) => r.error !== undefined && !r.binary).length;
+        const filesRead = fileResults.length - filesBinary - filesErrored;
+        const totalLines = fileResults.reduce((s, r) => s + r.lineCount, 0);
+        const totalTokens = fileResults.reduce((s, r) => s + r.tokenEstimate, 0);
+        const output = {
+            success: true,
+            summary: {
+                files_read: filesRead,
+                files_binary: filesBinary,
+                files_errored: filesErrored,
+                total_lines: totalLines,
+                total_tokens: totalTokens,
+            },
+            ...(images.length > 0 ? { images } : {}),
+        };
+        if (format === 'count_only') {
+            // summary only
+        }
+        else if (format === 'minimal') {
+            output.files = fileResults.map((r) => ({
+                path: r.path,
+                resolvedPath: r.resolvedPath,
+                lineCount: r.lineCount,
+                byteSize: r.byteSize,
+                tokenEstimate: r.tokenEstimate,
+                extract: r.extract,
+                binary: r.binary,
+                error: r.error,
+                cache: r.cache,
+            }));
+        }
+        else if (format === 'standard' || format === 'verbose') {
+            output.files = fileResults;
+        }
+        if (paginationInfo) {
+            output.pagination = paginationInfo;
+        }
+        return { success: true, output: JSON.stringify(output) };
+    }
+}

package/dist/platform/tools/read/media.d.ts

@@ -0,0 +1,111 @@
+/** Controls how image files are processed when read. */
+export type ImageMode = 'default' | 'unoptimized' | 'metadata-only' | 'thumbnail-only';
+/**
+ * Resize target (max edge in px) per ImageMode.
+ * null means no resizing (either no image data at all, or full resolution).
+ */
+export declare const RESIZE_TARGETS: Record<ImageMode, number | null>;
+export declare const IMAGE_SIZE_LIMIT: number;
+export declare const IMAGE_EXTENSIONS: Set<string>;
+export declare const IMAGE_MEDIA_TYPES: Record<string, string>;
+export declare const ARCHIVE_EXTENSIONS: Set<string>;
+/**
+ * Validate that the file's magic bytes match the expected extension.
+ * If they don't match, attempts to detect the actual type.
+ */
+export declare function validateMagicBytes(buffer: Buffer, ext: string): {
+    valid: boolean;
+    detectedType?: string;
+};
+/** Returns true when the extension belongs to a supported image format. */
+export declare function isImageFile(ext: string): boolean;
+/** Returns true when the extension belongs to a supported archive format. */
+export declare function isArchiveFile(ext: string): boolean;
+/** Returns the MIME type for an image extension, or null if unknown. */
+export declare function getImageMediaType(ext: string): string | null;
+export interface ImageMetadata {
+    width?: number;
+    height?: number;
+    format: string;
+    fileSize: number;
+}
+/**
+ * Extract basic image metadata from a buffer.
+ * Supports PNG, JPEG, GIF, BMP. Returns format + fileSize for others.
+ */
+export declare function getImageMetadata(buffer: Buffer, ext: string): ImageMetadata;
+/**
+ * Minimal sharp interface covering only the operations used here.
+ * Avoids requiring @types/sharp or the sharp package to be installed.
+ */
+interface SharpInstance {
+    metadata(): Promise<{
+        width?: number;
+        height?: number;
+        format?: string;
+    }>;
+    resize(options: {
+        width?: number;
+        height?: number;
+    }): SharpInstance;
+    png(): SharpInstance;
+    jpeg(): SharpInstance;
+    toBuffer(options: {
+        resolveWithObject: true;
+    }): Promise<{
+        data: Buffer;
+        info: {
+            width: number;
+            height: number;
+        };
+    }>;
+    toBuffer(): Promise<Buffer>;
+}
+type SharpFactory = (input: Buffer) => SharpInstance;
+/**
+ * Lazy-load sharp.
+ * Returns the sharp factory function on success, null if unavailable.
+ */
+export declare function tryLoadSharp(): Promise<SharpFactory | null>;
+export interface ResizeResult {
+    buffer: Buffer;
+    resized: boolean;
+    width?: number;
+    height?: number;
+}
+/**
+ * Resize an image buffer so its longest edge is ≤ maxEdge.
+ * If sharp is unavailable or the image is already small enough, returns the original.
+ *
+ * @remarks
+ * Format conversion notes (intentional for LLM consumption):
+ * - WebP input is converted to PNG (losing WebP compression efficiency), since
+ *   sharp's resize pipeline outputs JPEG or PNG only.
+ * - GIF input loses animation — only the first frame is preserved.
+ * - These trade-offs are intentional: LLMs expect static raster images.
+ */
+export declare function resizeImage(buffer: Buffer, mediaType: string, maxEdge: number): Promise<ResizeResult>;
+export interface ConvertResult {
+    buffer: Buffer;
+    mediaType: string;
+    converted: boolean;
+    originalFormat: string;
+}
+/**
+ * Convert non-portable image formats (BMP, TIFF, AVIF) to PNG using sharp.
+ * Returns the original buffer if sharp is unavailable or the format doesn't need conversion.
+ */
+export declare function convertToPortableFormat(buffer: Buffer, ext: string): Promise<ConvertResult>;
+export declare function humanSize(bytes: number): string;
+/**
+ * List the contents of an archive file.
+ * Supports ZIP, .gz (gunzip + tar parse if tar), .tar, .tgz.
+ */
+export declare function listArchiveContents(resolvedPath: string, buffer: Buffer, ext: string): string;
+/**
+ * Detect binary content by scanning for null bytes in the first sampleSize bytes.
+ * Returns true if null bytes are found (indicating binary content).
+ */
+export declare function isBinaryByContent(buffer: Buffer, sampleSize?: number): boolean;
+export {};
+//# sourceMappingURL=media.d.ts.map

package/dist/platform/tools/read/media.d.ts.map

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