dsh-file-convert 0.4.0

package/lib/core/utils/pages.d.ts

@@ -0,0 +1,12 @@
+import type { ConvertError } from '../types.js';
+export declare class PageRangeError extends Error {
+    readonly error: ConvertError;
+    constructor(error: ConvertError);
+}
+/**
+ * Parse a one-based, inclusive page selection like "1-3,5,8-10" into a
+ * deduplicated, ascending list of page numbers bounded by pageCount.
+ * Throws PageRangeError (code: invalid_input) on malformed or out-of-range
+ * selections so agents get a correction-friendly message.
+ */
+export declare function parsePageRange(spec: string, pageCount: number): number[];

package/lib/core/utils/pages.js

@@ -0,0 +1,46 @@
+import { convertError } from '../errors.js';
+export class PageRangeError extends Error {
+    error;
+    constructor(error) {
+        super(error.message);
+        this.error = error;
+    }
+}
+/**
+ * Parse a one-based, inclusive page selection like "1-3,5,8-10" into a
+ * deduplicated, ascending list of page numbers bounded by pageCount.
+ * Throws PageRangeError (code: invalid_input) on malformed or out-of-range
+ * selections so agents get a correction-friendly message.
+ */
+export function parsePageRange(spec, pageCount) {
+    const cleaned = spec.trim();
+    if (!cleaned) {
+        throw new PageRangeError(convertError('invalid_input', 'Page selection is empty.', {
+            hint: 'Use one-based ranges like 1-3,5,8-10.',
+        }));
+    }
+    if (!/^\d+(\s*-\s*\d+)?(\s*,\s*\d+(\s*-\s*\d+)?)*$/.test(cleaned)) {
+        throw new PageRangeError(convertError('invalid_input', `Invalid page selection: '${spec}'.`, {
+            hint: 'Use one-based ranges like 1-3,5,8-10 (commas separate pages and ranges).',
+        }));
+    }
+    const seen = new Set();
+    for (const part of cleaned.split(',')) {
+        const [rawStart, rawEnd] = part.split('-').map((s) => s.trim());
+        const start = Number.parseInt(rawStart, 10);
+        const end = rawEnd === undefined ? start : Number.parseInt(rawEnd, 10);
+        if (!Number.isInteger(start) || !Number.isInteger(end) || start < 1 || end < start) {
+            throw new PageRangeError(convertError('invalid_input', `Invalid page range '${part.trim()}' in '${spec}'.`, {
+                hint: 'Ranges must be ascending, one-based and inclusive, e.g. 2-4.',
+            }));
+        }
+        if (end > pageCount) {
+            throw new PageRangeError(convertError('invalid_input', `Page ${end} is out of range: the document has ${pageCount} page(s).`, {
+                hint: `Use page numbers between 1 and ${pageCount}.`,
+            }));
+        }
+        for (let p = start; p <= end; p++)
+            seen.add(p);
+    }
+    return [...seen].sort((a, b) => a - b);
+}

package/lib/format.d.ts

@@ -0,0 +1,23 @@
+import type { ConvertResult, ConversionStatus, InspectResult } from './core/index.js';
+export declare function formatBytes(n: number): string;
+export declare function formatDuration(ms: number): string;
+export declare function formatConvertResult(result: ConvertResult): string;
+export declare function formatFailure(error: {
+    code: string;
+    message: string;
+    detail?: string;
+    hint?: string;
+}): string;
+export declare function formatInspect(inspect: InspectResult): string;
+export declare function formatConversionList(statuses: ConversionStatus[]): string;
+export declare function formatBatchSummary(summary: BatchSummary): string;
+export interface BatchSummary {
+    inputDir: string;
+    outputDir?: string;
+    outputFormat: string;
+    converted: string[];
+    skipped: string[];
+    failed: string[];
+    /** Anything the user must know beyond the counts (e.g. truncation at the limit). */
+    notes: string[];
+}

package/lib/format.js

@@ -0,0 +1,84 @@
+/** Human-readable, agent-relayable text for conversion results. */
+const MAX_LISTED = 20;
+export function formatBytes(n) {
+    if (n < 1024)
+        return `${n} B`;
+    if (n < 1024 * 1024)
+        return `${(n / 1024).toFixed(1)} KB`;
+    return `${(n / 1024 / 1024).toFixed(1)} MB`;
+}
+export function formatDuration(ms) {
+    return ms >= 1000 ? `${(ms / 1000).toFixed(1)}s` : `${ms}ms`;
+}
+export function formatConvertResult(result) {
+    if (!result.ok)
+        return formatFailure(result.error);
+    const lines = [
+        `Converted: ${result.input} (${result.from}) -> ${result.output} (${result.to})`,
+        `${formatBytes(result.bytesIn)} -> ${formatBytes(result.bytesOut)} in ${formatDuration(result.durationMs)}`,
+    ];
+    if (result.outputs && result.outputs.length > 1) {
+        lines.push(`Outputs (${result.outputs.length}): ${result.outputs.slice(0, MAX_LISTED).join(', ')}` +
+            (result.outputs.length > MAX_LISTED ? ` … +${result.outputs.length - MAX_LISTED} more` : ''));
+    }
+    for (const warning of result.warnings)
+        lines.push(`Warning: ${warning}`);
+    return lines.join('\n');
+}
+export function formatFailure(error) {
+    const lines = [`Conversion failed (${error.code}): ${error.message}`];
+    if (error.hint)
+        lines.push(`Hint: ${error.hint}`);
+    if (error.detail)
+        lines.push(`Detail: ${error.detail}`);
+    return lines.join('\n');
+}
+export function formatInspect(inspect) {
+    return JSON.stringify(inspect, null, 2);
+}
+export function formatConversionList(statuses) {
+    const width = Math.max(...statuses.map((s) => `${s.from} -> ${s.to}`.length)) + 2;
+    const rows = statuses.map((s) => {
+        const pair = `${s.from} -> ${s.to}`;
+        const label = pair.padEnd(width, ' ');
+        const state = s.available ? 'available' : `unavailable (missing: ${s.missing.join(', ')})`;
+        return `${label}${state}${s.experimental ? '  [experimental]' : ''}`;
+    });
+    const unavailable = statuses.filter((s) => !s.available).length;
+    const footer = unavailable === 0
+        ? `${statuses.length} conversions, all local, no external dependencies required.`
+        : `${statuses.length} conversions, ${unavailable} unavailable. Install the missing tool to enable them.`;
+    return rows.join('\n') + '\n' + footer;
+}
+export function formatBatchSummary(summary) {
+    const lines = [
+        `Batch convert in ${summary.inputDir} -> ${summary.outputFormat.toUpperCase()}`,
+        `Converted: ${summary.converted.length}, skipped: ${summary.skipped.length}, failed: ${summary.failed.length}`,
+    ];
+    if (summary.outputDir)
+        lines.push(`Output dir: ${summary.outputDir}`);
+    for (const note of summary.notes)
+        lines.push(`Note: ${note}`);
+    if (summary.converted.length > 0) {
+        lines.push(`Recently converted:`);
+        for (const item of summary.converted.slice(0, MAX_LISTED))
+            lines.push(`  + ${item}`);
+        if (summary.converted.length > MAX_LISTED)
+            lines.push(`  … +${summary.converted.length - MAX_LISTED} more`);
+    }
+    if (summary.skipped.length > 0) {
+        lines.push(`Skipped (already exists, pass overwrite:true to replace):`);
+        for (const item of summary.skipped.slice(0, MAX_LISTED))
+            lines.push(`  = ${item}`);
+        if (summary.skipped.length > MAX_LISTED)
+            lines.push(`  … +${summary.skipped.length - MAX_LISTED} more`);
+    }
+    if (summary.failed.length > 0) {
+        lines.push(`Failed:`);
+        for (const item of summary.failed.slice(0, MAX_LISTED))
+            lines.push(`  x ${item}`);
+        if (summary.failed.length > MAX_LISTED)
+            lines.push(`  … +${summary.failed.length - MAX_LISTED} more`);
+    }
+    return lines.join('\n');
+}

package/lib/index.d.ts

@@ -0,0 +1,6 @@
+import type { Context } from '@deepseek-ai/cordis';
+import { type Config as ConvertConfig } from './config.js';
+export { Config } from './config.js';
+export declare const name = "dsh-file-convert";
+export declare const inject: string[];
+export declare function apply(ctx: Context, config: ConvertConfig): void;

package/lib/index.js

@@ -0,0 +1,51 @@
+import { createRouter } from './core/index.js';
+import { createConvertFileTool } from './tools/convert-file.js';
+import { createBatchConvertTool } from './tools/batch-convert.js';
+import { createInspectFileTool } from './tools/inspect-file.js';
+import { createListConversionsTool } from './tools/list-conversions.js';
+import { createOptimizeFileTool } from './tools/optimize-file.js';
+import { createInstallMediaTool } from './tools/install-media.js';
+import { createInstallOcrTool } from './tools/install-ocr.js';
+export { Config } from './config.js';
+export const name = 'dsh-file-convert';
+export const inject = ['tools'];
+const CONSOLE_LOGGER = {
+    debug: () => { },
+    info: (msg) => console.log(`[dsh-file-convert] ${msg}`),
+    warn: (msg) => console.warn(`[dsh-file-convert] ${msg}`),
+    error: (msg) => console.error(`[dsh-file-convert] ${msg}`),
+};
+export function apply(ctx, config) {
+    const logger = isLogger(ctx.logger) ? ctx.logger : CONSOLE_LOGGER;
+    const router = createRouter({
+        quality: config.quality,
+        dpi: config.dpi,
+        timeoutMs: config.timeoutMs,
+        outputRoots: config.outputRoots,
+        binaryOverrides: {
+            ...(config.ffmpegPath ? { ffmpegPath: config.ffmpegPath } : {}),
+            ...(config.ffprobePath ? { ffprobePath: config.ffprobePath } : {}),
+            ...(config.sofficePath ? { sofficePath: config.sofficePath } : {}),
+            ...(config.ghostscriptPath ? { ghostscriptPath: config.ghostscriptPath } : {}),
+            ...(config.pythonPath ? { pythonPath: config.pythonPath } : {}),
+            ...(config.tesseractPath ? { tesseractPath: config.tesseractPath } : {}),
+        },
+        maxInputBytes: config.maxInputMb * 1024 * 1024,
+        maxPdfPages: config.maxPdfPages,
+        maxOutputPixels: config.maxOutputPixels,
+    });
+    ctx.tools.register(createConvertFileTool(router, config, logger));
+    ctx.tools.register(createBatchConvertTool(router, config, logger));
+    ctx.tools.register(createInspectFileTool(router, config, logger));
+    ctx.tools.register(createListConversionsTool(router, logger));
+    ctx.tools.register(createOptimizeFileTool(router, config, logger));
+    ctx.tools.register(createInstallMediaTool(config, logger));
+    ctx.tools.register(createInstallOcrTool(config, logger));
+    logger.info('dsh-file-convert loaded: 7 tools registered (26 conversions; media/ocr dependencies install on request)');
+}
+function isLogger(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        typeof value.info === 'function' &&
+        typeof value.warn === 'function');
+}

package/lib/tools/batch-convert.d.ts

@@ -0,0 +1,5 @@
+import type { ConversionRouter, Logger } from '../core/index.js';
+import { DetectError } from '../core/index.js';
+import type { Config } from '../config.js';
+export declare function createBatchConvertTool(router: ConversionRouter, config: Config, logger: Logger): import("@deepseek-ai/dsh-tools").ToolDefinition;
+export { DetectError };

package/lib/tools/batch-convert.js

@@ -0,0 +1,155 @@
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { formatFromExtension, parseFormatArg } from '../core/index.js';
+import { batchOutputPath } from '../core/index.js';
+import { detectFile, DetectError } from '../core/index.js';
+import { formatBatchSummary } from '../format.js';
+const MAX_CONCURRENCY = 4;
+export function createBatchConvertTool(router, config, logger) {
+    return defineTool({
+        name: 'batch_convert',
+        description: 'Convert every matching file in a directory in one call (top level only), e.g. "convert all JPGs in this folder to WebP". Local execution, no uploads. Outputs land in <input_dir>/output by default; existing outputs are skipped unless overwrite is true.',
+        parameters: {
+            input_dir: { type: 'string', required: true, description: 'Directory containing the input files (non-recursive).' },
+            output_format: {
+                type: 'string',
+                required: true,
+                description: 'Target format: png, jpg, webp, svg, pdf, json, yaml, csv or txt.',
+            },
+            input_format: {
+                type: 'string',
+                description: 'Only convert files of this source format (e.g. jpg). Omit to auto-detect convertible files.',
+            },
+            output_dir: { type: 'string', description: 'Output directory. Default: <input_dir>/output.' },
+            overwrite: { type: 'boolean', description: 'Replace existing outputs. Default false (skip them).' },
+            quality: { type: 'integer', description: 'JPEG/WebP quality 1-100 (default from plugin config, 85).' },
+            dpi: { type: 'integer', description: 'Rasterization DPI for PDF/SVG inputs (default from plugin config, 150).' },
+            pages: { type: 'string', description: "Page selection for PDF inputs, e.g. '1-3,5' (one-based, inclusive)." },
+            ocr: { type: 'boolean', description: 'OCR pdf -> txt conversions for scanned documents. Slower.' },
+            ocr_lang: { type: 'string', description: "OCR languages, '+'-separated. Default 'chi_sim+eng'." },
+        },
+        output: {
+            schema: { type: 'string' },
+            render: (_args, value) => [{ type: 'text', text: value }],
+        },
+        timeoutMs: config.timeoutMs * 4,
+        isConcurrencySafe: () => true,
+        async execute(args, exec) {
+            const to = parseFormatArg(args.output_format);
+            if (!to)
+                throw new Error(`Unknown output format '${args.output_format}'. Supported: png, jpg, webp, svg, pdf, json, yaml, csv, txt.`);
+            const fromFilter = args.input_format
+                ? (() => {
+                    const parsed = parseFormatArg(args.input_format);
+                    if (!parsed)
+                        throw new Error(`Unknown source format '${args.input_format}'.`);
+                    return parsed;
+                })()
+                : undefined;
+            const inputDir = args.input_dir;
+            let entries;
+            try {
+                entries = await fs.readdir(inputDir, { withFileTypes: true });
+            }
+            catch (err) {
+                throw new Error(`Cannot read directory ${inputDir}: ${err instanceof Error ? err.message : String(err)}`);
+            }
+            const files = entries.filter((e) => e.isFile()).map((e) => path.join(inputDir, e.name)).sort();
+            const maxFiles = config.batchMaxFiles;
+            const candidates = [];
+            let examined = 0;
+            let truncated = false;
+            for (const file of files) {
+                if (candidates.length >= maxFiles) {
+                    truncated = true;
+                    break;
+                }
+                examined++;
+                if (fromFilter) {
+                    const ext = path.extname(file).replace(/^\./, '');
+                    if (formatFromExtension(ext) === fromFilter)
+                        candidates.push({ file, from: fromFilter });
+                    continue;
+                }
+                try {
+                    const { detection } = await detectFile(file);
+                    if (detection.format !== to && router.route(detection.format, to)) {
+                        candidates.push({ file, from: detection.format });
+                    }
+                }
+                catch {
+                    /* unknown formats are simply not candidates */
+                }
+            }
+            const notExamined = files.length - examined;
+            if (candidates.length === 0) {
+                return `No convertible files found in ${inputDir}${fromFilter ? ` with format ${fromFilter}` : ''}.`;
+            }
+            const notes = [];
+            if (truncated) {
+                notes.push(`Reached the ${maxFiles}-file batch limit; ${notExamined} file(s) in the directory were not processed. ` +
+                    `Raise 'batchMaxFiles' in the plugin config or narrow the run with 'input_format', then convert again.`);
+            }
+            const outputDir = args.output_dir ?? path.join(inputDir, 'output');
+            await fs.mkdir(outputDir, { recursive: true });
+            const summary = {
+                inputDir,
+                outputDir,
+                outputFormat: to,
+                converted: [],
+                skipped: [],
+                failed: [],
+                notes,
+            };
+            // The pool adapts to the strictest converter involved (ffmpeg = 2, sharp = 4).
+            const involvedConcurrency = new Set();
+            for (const candidate of candidates) {
+                const converter = router.route(candidate.from, to);
+                if (converter)
+                    involvedConcurrency.add(converter.concurrency);
+            }
+            const poolSize = Math.max(1, Math.min(MAX_CONCURRENCY, os.cpus().length, ...(involvedConcurrency.size ? involvedConcurrency : [MAX_CONCURRENCY])));
+            let next = 0;
+            let aborted = false;
+            const worker = async () => {
+                while (next < candidates.length) {
+                    if (exec.signal.aborted) {
+                        aborted = true;
+                        return;
+                    }
+                    const candidate = candidates[next++];
+                    const result = await router.convertFile({
+                        input: candidate.file,
+                        outputFormat: to,
+                        output: batchOutputPath(outputDir, candidate.file, to),
+                        overwrite: args.overwrite,
+                        quality: args.quality,
+                        dpi: args.dpi,
+                        pages: args.pages,
+                        ocr: args.ocr,
+                        ocrLang: args.ocr_lang,
+                    }, { logger, signal: exec.signal });
+                    const name = path.basename(candidate.file);
+                    if (result.ok) {
+                        summary.converted.push(`${name} -> ${path.relative(outputDir, result.output) || path.basename(result.output)}`);
+                    }
+                    else if (result.error.code === 'output_exists') {
+                        summary.skipped.push(name);
+                    }
+                    else {
+                        summary.failed.push(`${name}: ${result.error.message}`);
+                    }
+                }
+            };
+            await Promise.all(Array.from({ length: poolSize }, worker));
+            if (aborted) {
+                summary.failed.push(`Cancelled with ${candidates.length - next} files not processed.`);
+            }
+            return formatBatchSummary(summary);
+        },
+    });
+}
+// DetectError is re-exported for tests that assert detection failures.
+export { DetectError };

package/lib/tools/convert-file.d.ts

@@ -0,0 +1,3 @@
+import type { ConversionRouter, Logger } from '../core/index.js';
+import type { Config } from '../config.js';
+export declare function createConvertFileTool(router: ConversionRouter, config: Config, logger: Logger): import("@deepseek-ai/dsh-tools").ToolDefinition;

package/lib/tools/convert-file.js

@@ -0,0 +1,57 @@
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { formatConvertResult, formatFailure } from '../format.js';
+export function createConvertFileTool(router, config, logger) {
+    return defineTool({
+        name: 'convert_file',
+        description: 'Convert one file between supported formats, fully local: PNG/JPG/WEBP/SVG images, PDF (to PNG/JPG/TXT), JSON/YAML/CSV data. No API keys, no uploads, no token cost. The output file defaults to the input directory with the new extension. Use inspect_file first when the input is unclear, and list_conversions to see what is supported.',
+        parameters: {
+            input: { type: 'string', required: true, description: 'Absolute path of the file to convert.' },
+            output_format: {
+                type: 'string',
+                required: true,
+                description: 'Target format: png, jpg, webp, svg, pdf, json, yaml, csv or txt. Aliases like jpeg/yml are accepted.',
+            },
+            output: {
+                type: 'string',
+                description: 'Optional absolute output path. Defaults to next to the input file. If the plugin config sets outputRoots, the path must be inside one of them.',
+            },
+            overwrite: { type: 'boolean', description: 'Replace the output file if it exists. Default false.' },
+            quality: { type: 'integer', description: 'JPEG/WebP quality 1-100 (default from plugin config, 85).' },
+            dpi: { type: 'integer', description: 'Rasterization DPI for PDF/SVG inputs (default from plugin config, 150).' },
+            pages: {
+                type: 'string',
+                description: "Page selection for PDF inputs, one-based and inclusive: '1-3,5,8-10'. Outputs keep their real page numbers. Applies to pdf -> png/jpg/txt.",
+            },
+            ocr: {
+                type: 'boolean',
+                description: 'OCR the pages instead of reading the text layer (pdf -> txt only). For scanned PDFs. Uses a local Tesseract when installed, otherwise the bundled tesseract.js (slower; downloads language data on first use).',
+            },
+            ocr_lang: {
+                type: 'string',
+                description: "OCR languages, '+'-separated. Default 'chi_sim+eng'.",
+            },
+        },
+        output: {
+            schema: { type: 'string' },
+            render: (_args, value) => [{ type: 'text', text: value }],
+        },
+        timeoutMs: config.timeoutMs,
+        isConcurrencySafe: () => true,
+        async execute(args, exec) {
+            const result = await router.convertFile({
+                input: args.input,
+                outputFormat: args.output_format,
+                output: args.output,
+                overwrite: args.overwrite,
+                quality: args.quality,
+                dpi: args.dpi,
+                pages: args.pages,
+                ocr: args.ocr,
+                ocrLang: args.ocr_lang,
+            }, { logger, signal: exec.signal });
+            if (!result.ok)
+                throw new Error(formatFailure(result.error));
+            return formatConvertResult(result);
+        },
+    });
+}

package/lib/tools/inspect-file.d.ts

@@ -0,0 +1,3 @@
+import type { ConversionRouter, Logger } from '../core/index.js';
+import type { Config } from '../config.js';
+export declare function createInspectFileTool(router: ConversionRouter, config: Config, logger: Logger): import("@deepseek-ai/dsh-tools").ToolDefinition;

package/lib/tools/inspect-file.js

@@ -0,0 +1,29 @@
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { DetectError } from '../core/index.js';
+import { formatFailure, formatInspect } from '../format.js';
+export function createInspectFileTool(router, config, logger) {
+    void logger;
+    return defineTool({
+        name: 'inspect_file',
+        description: 'Inspect a file before converting it: format (by content, not just extension), dimensions for images, page count / encryption / scanned-PDF detection for PDFs, record counts for JSON/YAML/CSV, plus file size. Returns JSON.',
+        parameters: {
+            input: { type: 'string', required: true, description: 'Absolute path of the file to inspect.' },
+        },
+        output: {
+            schema: { type: 'string' },
+            render: (_args, value) => [{ type: 'text', text: value }],
+        },
+        timeoutMs: Math.min(config.timeoutMs, 30_000),
+        isConcurrencySafe: () => true,
+        async execute(args) {
+            try {
+                return formatInspect(await router.inspect(args.input));
+            }
+            catch (err) {
+                if (err instanceof DetectError)
+                    throw new Error(formatFailure(err.error));
+                throw err;
+            }
+        },
+    });
+}

package/lib/tools/install-media.d.ts

@@ -0,0 +1,9 @@
+import type { Logger } from '../core/index.js';
+import type { Config } from '../config.js';
+/**
+ * One explicit, user-approved path to media support: downloads pinned static
+ * ffmpeg/ffprobe builds (FFmpeg 6.1.1) into the plugin cache via the
+ * npmmirror binary CDN, with the GitHub release as a sha256-identical
+ * fallback. System installs always keep priority; this only fills the gap.
+ */
+export declare function createInstallMediaTool(config: Config, logger: Logger): import("@deepseek-ai/dsh-tools").ToolDefinition;

package/lib/tools/install-media.js

@@ -0,0 +1,55 @@
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { FFMPEG, FFPROBE, resolveBinary } from '../core/index.js';
+import { downloadBinary } from '../core/binaries/download.js';
+import { formatBytes } from '../format.js';
+/**
+ * One explicit, user-approved path to media support: downloads pinned static
+ * ffmpeg/ffprobe builds (FFmpeg 6.1.1) into the plugin cache via the
+ * npmmirror binary CDN, with the GitHub release as a sha256-identical
+ * fallback. System installs always keep priority; this only fills the gap.
+ */
+export function createInstallMediaTool(config, logger) {
+    return defineTool({
+        name: 'install_media_dependencies',
+        description: 'Download pinned static ffmpeg and ffprobe builds (FFmpeg 6.1.1, about 56 MB total on Windows as two ~28 MB downloads) into the plugin cache (~/.dsh-file-convert/bin), so mp4/mov/wav conversions and video optimize_file work without a system install. Served from the npmmirror binary CDN with the GitHub release as fallback, both sha256-verified. Ask the user for consent before calling. Skips what is already available; a system ffmpeg keeps priority over the cache.',
+        parameters: {
+            force: {
+                type: 'boolean',
+                description: 'Re-download even if a cached copy exists (e.g. after a corrupted download). Default false.',
+            },
+        },
+        output: {
+            schema: { type: 'string' },
+            render: (_args, value) => [{ type: 'text', text: value }],
+        },
+        timeoutMs: Math.max(config.timeoutMs, 900_000), // big files, slow networks
+        isConcurrencySafe: () => false,
+        async execute(args, exec) {
+            const overrides = {};
+            if (config.ffmpegPath)
+                overrides.ffmpegPath = config.ffmpegPath;
+            if (config.ffprobePath)
+                overrides.ffprobePath = config.ffprobePath;
+            const lines = [];
+            for (const dep of [FFMPEG, FFPROBE]) {
+                const existing = await resolveBinary(dep, overrides, logger);
+                if (existing && args.force !== true) {
+                    lines.push(`= ${dep.name}: already available at ${existing}`);
+                    continue;
+                }
+                logger.info(`downloading ${dep.name} into the plugin cache...`);
+                const outcome = await downloadBinary(dep, {
+                    timeoutMs: Math.max(config.timeoutMs, 900_000),
+                    signal: exec.signal,
+                    force: args.force === true,
+                });
+                lines.push(`+ ${dep.name}: installed at ${outcome.path} (${formatBytes(outcome.bytes)}) - ${outcome.versionLine}`);
+            }
+            return [
+                'Media dependencies ready:',
+                ...lines,
+                'No restart needed - the cache is checked on every conversion.',
+            ].join('\n');
+        },
+    });
+}

package/lib/tools/install-ocr.d.ts

@@ -0,0 +1,7 @@
+import type { Logger } from '../core/index.js';
+import type { Config } from '../config.js';
+/**
+ * Explicit consent path for OCR language data: downloads tesseract.js packs
+ * into the plugin cache. Conversions never download these implicitly.
+ */
+export declare function createInstallOcrTool(config: Config, logger: Logger): import("@deepseek-ai/dsh-tools").ToolDefinition;

package/lib/tools/install-ocr.js

@@ -0,0 +1,43 @@
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { TESSERACT, installOcrLanguages, ocrLanguagesCached, resolveBinary, tessdataDir } from '../core/index.js';
+import { formatBytes } from '../format.js';
+/**
+ * Explicit consent path for OCR language data: downloads tesseract.js packs
+ * into the plugin cache. Conversions never download these implicitly.
+ */
+export function createInstallOcrTool(config, logger) {
+    return defineTool({
+        name: 'install_ocr_dependencies',
+        description: 'Download OCR language data for the bundled tesseract.js engine (about 10-30 MB per language, cached in ~/.dsh-file-convert/tessdata) so pdf -> txt with ocr: true works without a local Tesseract. Ask the user for consent before calling. Skips when a local Tesseract CLI is installed or the data is already cached.',
+        parameters: {
+            lang: { type: 'string', description: "OCR languages, '+'-separated. Default 'chi_sim+eng'." },
+            force: { type: 'boolean', description: 'Re-download even if the language data is already cached. Default false.' },
+        },
+        output: {
+            schema: { type: 'string' },
+            render: (_args, value) => [{ type: 'text', text: value }],
+        },
+        timeoutMs: Math.max(config.timeoutMs, 900_000),
+        isConcurrencySafe: () => false,
+        async execute(args, exec) {
+            const lang = args.lang ?? 'chi_sim+eng';
+            const overrides = {};
+            if (config.tesseractPath)
+                overrides.tesseractPath = config.tesseractPath;
+            const cli = await resolveBinary(TESSERACT, overrides, logger);
+            if (cli && args.force !== true) {
+                return `Local Tesseract found at ${cli} - OCR works without any download (languages come from its own traineddata).`;
+            }
+            if (args.force !== true && (await ocrLanguagesCached(lang))) {
+                return `Language data for '${lang}' is already cached in ${tessdataDir()}. Nothing to do.`;
+            }
+            const t0 = Date.now();
+            const { files, bytes } = await installOcrLanguages(lang, { logger, signal: exec.signal });
+            return [
+                'OCR language data ready:',
+                `+ ${lang}: ${files.join(', ')} (${formatBytes(bytes)}) in the plugin cache`,
+                `Downloaded in ${Math.round((Date.now() - t0) / 100) / 10}s. No restart needed.`,
+            ].join('\n');
+        },
+    });
+}

package/lib/tools/list-conversions.d.ts

@@ -0,0 +1,2 @@
+import type { ConversionRouter, Logger } from '../core/index.js';
+export declare function createListConversionsTool(router: ConversionRouter, logger: Logger): import("@deepseek-ai/dsh-tools").ToolDefinition;

package/lib/tools/list-conversions.js

@@ -0,0 +1,18 @@
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { formatConversionList } from '../format.js';
+export function createListConversionsTool(router, logger) {
+    void logger;
+    return defineTool({
+        name: 'list_conversions',
+        description: 'List every conversion dsh-file-convert supports on this machine, including which ones are unavailable because an external tool is missing. Call this before converting when unsure whether a pair is supported.',
+        parameters: {},
+        output: {
+            schema: { type: 'string' },
+            render: (_args, value) => [{ type: 'text', text: value }],
+        },
+        isConcurrencySafe: () => true,
+        async execute() {
+            return formatConversionList(await router.listConversions());
+        },
+    });
+}

package/lib/tools/optimize-file.d.ts

@@ -0,0 +1,3 @@
+import type { ConversionRouter, Logger } from '../core/index.js';
+import type { Config } from '../config.js';
+export declare function createOptimizeFileTool(router: ConversionRouter, config: Config, logger: Logger): import("@deepseek-ai/dsh-tools").ToolDefinition;