dsh-file-convert 0.4.0

package/lib/core/inspect.js

@@ -0,0 +1,134 @@
+import fs from 'node:fs/promises';
+import sharp from 'sharp';
+import yaml from 'js-yaml';
+import { parse as csvParse } from 'csv-parse/sync';
+import { probeMedia } from './utils/exec.js';
+import './converters/pdf-env.js';
+/**
+ * Structured file facts so an agent can decide before converting.
+ * Inspect is informational: parse problems degrade to `kind: 'unknown'`
+ * (or `probeUnavailable` for media) instead of failing.
+ */
+export async function inspectFile(input, detection, bytes, media) {
+    switch (detection.format) {
+        case 'png':
+        case 'jpg':
+        case 'webp':
+        case 'svg':
+        case 'gif':
+            return inspectImage(input, detection.format, bytes);
+        case 'pdf':
+            return inspectPdf(input, bytes);
+        case 'mp4':
+        case 'mov':
+        case 'mp3':
+        case 'wav':
+            return inspectMedia(input, detection.format, bytes, media);
+        case 'json':
+        case 'yaml':
+        case 'csv':
+        case 'txt':
+            return inspectData(input, detection.format, bytes);
+        default:
+            return { kind: 'unknown', bytes, mime: detection.mime };
+    }
+}
+async function inspectImage(input, format, bytes) {
+    try {
+        const meta = await sharp(input).metadata();
+        return {
+            kind: 'image',
+            format,
+            width: meta.width ?? 0,
+            height: meta.height ?? 0,
+            channels: meta.channels,
+            bytes,
+        };
+    }
+    catch {
+        return { kind: 'unknown', bytes };
+    }
+}
+async function inspectMedia(input, format, bytes, probe) {
+    const base = { kind: 'media', format, bytes };
+    if (!probe)
+        return { ...base, probeUnavailable: true };
+    const parsed = await probeMedia(probe.ffprobePath, input, probe.timeoutMs, probe.signal).catch(() => null);
+    if (!parsed)
+        return { ...base, probeUnavailable: true };
+    const video = parsed.streams?.find((s) => s.codec_type === 'video');
+    const audio = parsed.streams?.find((s) => s.codec_type === 'audio');
+    return {
+        ...base,
+        durationSec: parsed.format?.duration ? Number.parseFloat(parsed.format.duration) : undefined,
+        width: video?.width,
+        height: video?.height,
+        fps: parseFps(video?.r_frame_rate),
+        audioCodec: audio?.codec_name,
+    };
+}
+/** '30/1' -> 30; '2997/100' -> 29.97; garbage/zero denominator -> undefined. */
+function parseFps(rFrameRate) {
+    if (!rFrameRate)
+        return undefined;
+    const [num, den] = rFrameRate.split('/', 2).map(Number);
+    if (!Number.isFinite(num) || !Number.isFinite(den) || den === 0)
+        return undefined;
+    const fps = num / den;
+    return Number.isFinite(fps) && fps > 0 ? Number(fps.toFixed(3)) : undefined;
+}
+async function inspectPdf(input, bytes) {
+    const { getDocument } = await import('pdfjs-dist/legacy/build/pdf.mjs');
+    try {
+        const data = new Uint8Array(await fs.readFile(input));
+        const doc = await getDocument({ data, verbosity: 0 }).promise;
+        try {
+            let chars = 0;
+            for (let n = 1; n <= Math.min(3, doc.numPages); n++) {
+                const page = await doc.getPage(n);
+                const content = await page.getTextContent();
+                for (const item of content.items)
+                    chars += item.str?.trim().length ?? 0;
+                page.cleanup();
+            }
+            const pagesInspected = Math.min(3, doc.numPages);
+            return {
+                kind: 'pdf',
+                pages: doc.numPages,
+                encrypted: false,
+                likelyScanned: chars / pagesInspected < 40,
+                bytes,
+            };
+        }
+        finally {
+            await doc.cleanup().catch(() => undefined);
+        }
+    }
+    catch (err) {
+        const name = err instanceof Error ? err.name : '';
+        if (name === 'PasswordException') {
+            return { kind: 'pdf', pages: 0, encrypted: true, likelyScanned: false, bytes };
+        }
+        return { kind: 'unknown', bytes };
+    }
+}
+async function inspectData(input, format, bytes) {
+    try {
+        const raw = (await fs.readFile(input, 'utf8')).replace(/^\uFEFF/, '');
+        if (format === 'txt')
+            return { kind: 'data', format, bytes };
+        if (format === 'json') {
+            const value = JSON.parse(raw);
+            return { kind: 'data', format, records: Array.isArray(value) ? value.length : 1, bytes };
+        }
+        if (format === 'yaml') {
+            const value = yaml.load(raw);
+            return { kind: 'data', format, records: Array.isArray(value) ? value.length : 1, bytes };
+        }
+        const rows = csvParse(raw, { bom: true, columns: true, skip_empty_lines: true });
+        return { kind: 'data', format, records: rows.length, bytes };
+    }
+    catch {
+        return { kind: 'unknown', bytes };
+    }
+}

package/lib/core/ocr.d.ts

@@ -0,0 +1,38 @@
+import type { BinaryDependency, ConvertContext, Logger } from './types.js';
+/**
+ * Metadata for the tesseract.js language data, used in dependency errors.
+ * Conversions NEVER download it implicitly: without a cached pack they fail
+ * with guidance pointing at install_ocr_dependencies.
+ */
+export declare const OCR_LANGUAGE_DATA: BinaryDependency;
+export declare const TESSERACT: BinaryDependency;
+export interface OcrEngine {
+    name: string;
+    recognizePng(png: Buffer, lang: string, ctx: ConvertContext): Promise<string>;
+}
+export declare function tessdataDir(): string;
+/** True when every language of the set already sits in the plugin cache. */
+export declare function ocrLanguagesCached(lang: string): Promise<boolean>;
+/**
+ * Explicitly download the language data for `lang` by warming a worker.
+ * Called only from install_ocr_dependencies (user consented).
+ */
+export declare function installOcrLanguages(lang: string, ctx: {
+    logger: Logger;
+    signal?: AbortSignal;
+}): Promise<{
+    files: string[];
+    bytes: number;
+}>;
+/** Thrown by engines when the requested OCR language data is not available. */
+export declare class OcrLanguageMissingError extends Error {
+    readonly lang: string;
+    readonly detail?: string | undefined;
+    constructor(lang: string, detail?: string | undefined);
+}
+/**
+ * Pick an OCR engine: a locally installed Tesseract CLI first (fast, uses the
+ * system's trained language data), then the bundled tesseract.js as a pure-npm
+ * fallback. null = nothing usable (the caller reports how to fix it).
+ */
+export declare function resolveOcrEngine(resolve: (dep: BinaryDependency) => Promise<string | null>, logger: Logger): Promise<OcrEngine | null>;

package/lib/core/ocr.js

@@ -0,0 +1,152 @@
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { ExecError, execTool } from './utils/exec.js';
+import { cacheDir } from './binaries/cache.js';
+/**
+ * Metadata for the tesseract.js language data, used in dependency errors.
+ * Conversions NEVER download it implicitly: without a cached pack they fail
+ * with guidance pointing at install_ocr_dependencies.
+ */
+export const OCR_LANGUAGE_DATA = {
+    name: 'ocr-language-data',
+    displayName: 'OCR language data (tesseract.js)',
+    commands: [],
+    installHint: {
+        win32: 'run the install_ocr_dependencies tool',
+        darwin: 'run the install_ocr_dependencies tool',
+        linux: 'run the install_ocr_dependencies tool',
+    },
+};
+export const TESSERACT = {
+    name: 'tesseract',
+    displayName: 'Tesseract OCR',
+    commands: ['tesseract'],
+    configKey: 'tesseractPath',
+    extraPaths: {
+        win32: ['C:\\Program Files\\Tesseract-OCR\\tesseract.exe'],
+        darwin: ['/opt/homebrew/bin/tesseract', '/usr/local/bin/tesseract'],
+        linux: ['/usr/bin/tesseract', '/usr/local/bin/tesseract'],
+    },
+    installHint: {
+        win32: 'winget install UB-Mannheim.TesseractOCR (tick the chi_sim language component)',
+        darwin: 'brew install tesseract tesseract-lang',
+        linux: 'sudo apt install tesseract-ocr tesseract-ocr-chi-sim',
+    },
+};
+/** One warmed tesseract.js worker per language set, reused across pages. */
+const jsWorkers = new Map();
+async function jsWorker(lang) {
+    let pending = jsWorkers.get(lang);
+    if (!pending) {
+        pending = (async () => {
+            const { createWorker } = await import('tesseract.js');
+            // Language data (~10-30 MB per language) downloads into the plugin
+            // cache; only reached via install_ocr_dependencies' explicit consent.
+            const cachePath = path.join(cacheDir(), 'tessdata');
+            await fs.mkdir(cachePath, { recursive: true });
+            return createWorker(lang, 1, { cachePath });
+        })();
+        jsWorkers.set(lang, pending);
+        pending.catch(() => jsWorkers.delete(lang));
+    }
+    return pending;
+}
+export function tessdataDir() {
+    return path.join(cacheDir(), 'tessdata');
+}
+/** True when every language of the set already sits in the plugin cache. */
+export async function ocrLanguagesCached(lang) {
+    let entries = [];
+    try {
+        entries = await fs.readdir(tessdataDir());
+    }
+    catch {
+        return false;
+    }
+    return lang.split('+').every((l) => entries.some((e) => e.startsWith(`${l}.traineddata`)));
+}
+/**
+ * Explicitly download the language data for `lang` by warming a worker.
+ * Called only from install_ocr_dependencies (user consented).
+ */
+export async function installOcrLanguages(lang, ctx) {
+    void ctx.signal; // tesseract.js cannot abort mid-download; the tool's timeout applies
+    await jsWorker(lang); // creating the worker downloads the language data
+    const entries = await fs.readdir(tessdataDir()).catch(() => []);
+    const files = [];
+    let bytes = 0;
+    for (const l of lang.split('+')) {
+        const file = entries.find((e) => e.startsWith(`${l}.traineddata`));
+        if (!file) {
+            throw new Error(`Language data for '${l}' did not download; check network access to the tesseract.js CDN.`);
+        }
+        const stat = await fs.stat(path.join(tessdataDir(), file));
+        files.push(file);
+        bytes += stat.size;
+    }
+    return { files, bytes };
+}
+/** Thrown by engines when the requested OCR language data is not available. */
+export class OcrLanguageMissingError extends Error {
+    lang;
+    detail;
+    constructor(lang, detail) {
+        super(`OCR language data for '${lang}' is not available.`);
+        this.lang = lang;
+        this.detail = detail;
+    }
+}
+/**
+ * Pick an OCR engine: a locally installed Tesseract CLI first (fast, uses the
+ * system's trained language data), then the bundled tesseract.js as a pure-npm
+ * fallback. null = nothing usable (the caller reports how to fix it).
+ */
+export async function resolveOcrEngine(resolve, logger) {
+    const cli = await resolve(TESSERACT);
+    if (cli) {
+        logger.debug(`ocr engine: tesseract CLI at ${cli}`);
+        return {
+            name: 'tesseract-cli',
+            async recognizePng(png, lang, ctx) {
+                const tmp = path.join(os.tmpdir(), `dsh-ocr-${Date.now()}-${Math.random().toString(36).slice(2)}.png`);
+                await fs.writeFile(tmp, png);
+                try {
+                    const { stdout } = await execTool(cli, [tmp, 'stdout', '-l', lang], {
+                        timeoutMs: ctx.timeoutMs,
+                        signal: ctx.signal,
+                        maxStderrBytes: 8 * 1024,
+                    });
+                    return stdout;
+                }
+                catch (err) {
+                    // A CLI without the requested traineddata should read as a missing
+                    // dependency, not as a generic conversion failure.
+                    if (err instanceof ExecError && err.code === 'failed' && /failed loading language|error opening data file|didn't load any languages/i.test(err.stderr ?? '')) {
+                        throw new OcrLanguageMissingError(lang, err.stderr);
+                    }
+                    throw err;
+                }
+                finally {
+                    await fs.rm(tmp, { force: true }).catch(() => undefined);
+                }
+            },
+        };
+    }
+    try {
+        await import('tesseract.js');
+    }
+    catch (err) {
+        logger.debug(`ocr engine: tesseract.js unavailable (${err instanceof Error ? err.message : String(err)})`);
+        return null;
+    }
+    logger.debug('ocr engine: tesseract.js (bundled fallback)');
+    return {
+        name: 'tesseract.js',
+        async recognizePng(png, lang) {
+            const worker = await jsWorker(lang);
+            const { data } = await worker.recognize(png);
+            return data.text;
+        },
+    };
+}

package/lib/core/optimizers.d.ts

@@ -0,0 +1,29 @@
+import type { BinaryDependency, ConvertContext, ConvertError, FormatId } from './types.js';
+export declare const GHOSTSCRIPT: BinaryDependency;
+export type OptimizeResult = {
+    ok: true;
+    input: string;
+    output: string;
+    format: FormatId;
+    bytesIn: number;
+    bytesOut: number;
+    durationMs: number;
+    /** Human-readable summary of what was applied (bitrate, quality...). */
+    detail: string;
+    warnings: string[];
+} | {
+    ok: false;
+    error: ConvertError;
+};
+export interface BinaryResolver {
+    (dep: BinaryDependency): Promise<string | null>;
+}
+/**
+ * Shrink a file toward a target size, fully local.
+ * - mp4/mov video: two-pass x264 with a bitrate computed from the target
+ *   (output is always mp4; the container may change for MOV sources).
+ * - jpg/webp: binary-search the largest encoder quality that fits.
+ * - png: libimagequant palette search (lossy color reduction, by design).
+ * GIF and PDF optimization are not supported yet (pdf planned with V0.3).
+ */
+export declare function optimizeFile(input: string, targetBytes: number, output: string, format: FormatId, resolve: BinaryResolver, ctx: ConvertContext): Promise<OptimizeResult>;

package/lib/core/optimizers.js

@@ -0,0 +1,275 @@
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import sharp from 'sharp';
+import { ExecError, execTool, probeMedia } from './utils/exec.js';
+import { convertError } from './errors.js';
+import { FFMPEG, FFPROBE } from './converters/media.js';
+export const GHOSTSCRIPT = {
+    name: 'ghostscript',
+    displayName: 'Ghostscript',
+    commands: ['gswin64c', 'gswin32c', 'gs'],
+    configKey: 'ghostscriptPath',
+    extraPaths: {
+        // gs installs into a versioned directory and is not always on PATH
+        win32: ['C:\\Program Files\\gs\\gs*\\bin\\gswin64c.exe'],
+        darwin: ['/opt/homebrew/bin/gs', '/usr/local/bin/gs'],
+        linux: ['/usr/bin/gs', '/usr/local/bin/gs'],
+    },
+    installHint: {
+        win32: 'winget install ArtifexSoftware.GhostScript (or download from github.com/ArtifexSoftware/ghostpdl-downloads)',
+        darwin: 'brew install ghostscript',
+        linux: 'sudo apt install ghostscript',
+    },
+};
+const FFMPEG_GLOBAL = ['-hide_banner', '-nostdin', '-y'];
+/**
+ * Shrink a file toward a target size, fully local.
+ * - mp4/mov video: two-pass x264 with a bitrate computed from the target
+ *   (output is always mp4; the container may change for MOV sources).
+ * - jpg/webp: binary-search the largest encoder quality that fits.
+ * - png: libimagequant palette search (lossy color reduction, by design).
+ * GIF and PDF optimization are not supported yet (pdf planned with V0.3).
+ */
+export async function optimizeFile(input, targetBytes, output, format, resolve, ctx) {
+    const started = Date.now();
+    try {
+        const bytesIn = (await fs.stat(input)).size;
+        let bytesOut;
+        let detail;
+        const warnings = [];
+        if (bytesIn <= targetBytes) {
+            // Nothing to do: keep the source as the output so the caller always gets a file.
+            await fs.copyFile(input, output);
+            return {
+                ok: true, input, output, format,
+                bytesIn, bytesOut: bytesIn,
+                durationMs: Date.now() - started,
+                detail: `input (${bytesIn} bytes) is already below the target (${targetBytes} bytes); copied unchanged`,
+                warnings: [],
+            };
+        }
+        switch (format) {
+            case 'mp4':
+            case 'mov': {
+                const applied = await optimizeVideo(input, targetBytes, output, resolve, ctx);
+                detail = `two-pass x264: video ${applied.videoKbps}k + audio ${applied.audioKbps}k over ${applied.durationSec.toFixed(1)}s`;
+                break;
+            }
+            case 'jpg':
+            case 'webp': {
+                const used = await optimizeQuality(input, targetBytes, output, format);
+                detail = `${format} quality ${used}`;
+                break;
+            }
+            case 'png': {
+                const used = await optimizeQuality(input, targetBytes, output, 'png');
+                detail = `png palette quality ${used}`;
+                warnings.push('PNG palette mode reduces the color count; compare visually.');
+                break;
+            }
+            case 'pdf': {
+                const applied = await optimizePdf(input, targetBytes, output, resolve, ctx);
+                detail = applied.detail;
+                warnings.push(...applied.warnings);
+                break;
+            }
+            case 'gif':
+                return notPossible(input, format, 'GIF optimization is not supported yet.');
+            default:
+                return notPossible(input, format, `optimize_file supports mp4/mov video, jpg/webp/png images and pdf, not ${format}.`);
+        }
+        bytesOut = (await fs.stat(output)).size;
+        return { ok: true, input, output, format, bytesIn, bytesOut, durationMs: Date.now() - started, detail, warnings };
+    }
+    catch (err) {
+        if (err instanceof OptimizeError)
+            return { ok: false, error: err.error };
+        if (err instanceof ExecError) {
+            const code = err.code === 'timeout' ? 'timeout' : err.code === 'cancelled' ? 'cancelled' : 'conversion_failed';
+            return { ok: false, error: convertError(code, `Optimization failed (ffmpeg).`, { detail: err.stderr }) };
+        }
+        return { ok: false, error: convertError('conversion_failed', `Optimization failed for ${input}`, {
+                detail: err instanceof Error ? err.message : String(err),
+            }) };
+    }
+}
+class OptimizeError {
+    error;
+    constructor(error) {
+        this.error = error;
+    }
+}
+function notPossible(input, format, message) {
+    return {
+        ok: false,
+        error: convertError('unsupported_conversion', message, {
+            hint: `Use convert_file for ${format} instead.`,
+        }),
+    };
+}
+async function optimizeVideo(input, targetBytes, output, resolve, ctx) {
+    const ffmpeg = await requireBinary(resolve, FFMPEG, ctx);
+    const ffprobe = await requireBinary(resolve, FFPROBE, ctx);
+    const probe = await probeMedia(ffprobe, input, ctx.timeoutMs, ctx.signal);
+    const durationSec = Number.parseFloat(probe?.format?.duration ?? '');
+    if (!Number.isFinite(durationSec) || durationSec <= 0) {
+        throw new OptimizeError(convertError('invalid_input', 'Cannot determine the video duration (ffprobe returned nothing usable).'));
+    }
+    // Container overhead + muxing slack: aim at 95% of the target.
+    const totalKbits = (targetBytes * 0.95 * 8) / 1000;
+    let audioKbps = 128;
+    let videoKbps = Math.floor(totalKbits / durationSec) - audioKbps;
+    if (videoKbps < 50) {
+        audioKbps = 64;
+        videoKbps = Math.floor(totalKbits / durationSec) - audioKbps;
+    }
+    if (videoKbps < 30) {
+        const minBytes = Math.ceil(((30 + 64) * 1000 * durationSec) / 8 + 512 * 1024);
+        throw new OptimizeError(convertError('unsupported_conversion', `Target size is too small: this ${durationSec.toFixed(1)}s video needs at least about ${(minBytes / 1048576).toFixed(1)} MB.`, { hint: 'Increase target_size_mb, or shorten/trim the video first.' }));
+    }
+    const passlog = path.join(os.tmpdir(), `dsh-file-convert-pass-${Date.now()}`);
+    // pass 2 writes to a scratch file; the output path only ever sees a
+    // complete file, so an abort never leaves a broken mp4 behind.
+    const scratch = path.join(os.tmpdir(), `dsh-file-convert-out-${Date.now()}.mp4`);
+    try {
+        try {
+            await execTool(ffmpeg, [
+                ...FFMPEG_GLOBAL, '-i', input,
+                '-c:v', 'libx264', '-b:v', `${videoKbps}k`, '-pass', '1', '-passlogfile', passlog,
+                '-an', '-f', 'null', '-',
+            ], { timeoutMs: ctx.timeoutMs, signal: ctx.signal });
+            await execTool(ffmpeg, [
+                ...FFMPEG_GLOBAL, '-i', input,
+                '-c:v', 'libx264', '-b:v', `${videoKbps}k`, '-pass', '2', '-passlogfile', passlog,
+                '-c:a', 'aac', '-b:a', `${audioKbps}k`, '-movflags', '+faststart',
+                scratch,
+            ], { timeoutMs: ctx.timeoutMs, signal: ctx.signal });
+            await fs.copyFile(scratch, output);
+        }
+        catch (err) {
+            // Sources with broken DTS/timestamps (screen recordings, stitched clips)
+            // can fail pass 2; point users at the normalize-then-optimize path.
+            if (err instanceof ExecError && err.code === 'failed') {
+                throw new OptimizeError(convertError('conversion_failed', 'Two-pass encoding failed.', {
+                    detail: err.stderr,
+                    hint: 'If the source has unusual timestamps, run convert_file to MP4 first and optimize that result.',
+                }));
+            }
+            throw err;
+        }
+    }
+    finally {
+        await fs.rm(scratch, { force: true }).catch(() => undefined);
+        for (const suffix of ['-0.log', '-0.log.mbtree']) {
+            await fs.rm(passlog + suffix, { force: true }).catch(() => undefined);
+        }
+    }
+    return { videoKbps, audioKbps, durationSec };
+}
+/** Binary-search the highest encoder quality whose output fits the target. */
+async function optimizeQuality(input, targetBytes, output, format) {
+    const encode = async (quality) => {
+        const pipeline = sharp(input);
+        if (format === 'jpg')
+            return pipeline.flatten({ background: '#ffffff' }).jpeg({ quality }).toBuffer();
+        if (format === 'webp')
+            return pipeline.webp({ quality }).toBuffer();
+        return pipeline.png({ palette: true, quality, effort: 7 }).toBuffer();
+    };
+    const low = format === 'webp' ? 1 : format === 'png' ? 0 : 5;
+    const high = format === 'png' ? 100 : 95;
+    const floorBuffer = await encode(low);
+    if (floorBuffer.length > targetBytes) {
+        // Nothing fits: write the smallest variant and let the caller decide.
+        await fs.writeFile(output, floorBuffer);
+        return low;
+    }
+    let bestQuality = low;
+    let bestBuffer = floorBuffer;
+    let lo = low;
+    let hi = high;
+    while (hi - lo > 1) {
+        const mid = Math.floor((lo + hi) / 2);
+        const buffer = await encode(mid);
+        if (buffer.length <= targetBytes) {
+            bestQuality = mid;
+            bestBuffer = buffer;
+            lo = mid;
+        }
+        else {
+            hi = mid;
+        }
+    }
+    await fs.writeFile(output, bestBuffer);
+    return bestQuality;
+}
+/** Ghostscript presets, coarse to fine; keep the smallest produced result. */
+const PDF_PRESETS = [
+    { name: 'printer (300 dpi)', setting: '/printer' },
+    { name: 'ebook (150 dpi)', setting: '/ebook' },
+    { name: 'screen (72 dpi)', setting: '/screen' },
+];
+async function optimizePdf(input, targetBytes, output, resolve, ctx) {
+    const gs = await requireBinary(resolve, GHOSTSCRIPT, ctx);
+    // Default SAFER mode applies: the command-line input file and the explicit
+    // -sOutputFile are both inside its allowlist, so no -dNOSAFER is needed.
+    const base = [
+        '-dNOPAUSE', '-dBATCH', '-dQUIET',
+        '-sDEVICE=pdfwrite', '-dCompatibilityLevel=1.4',
+    ];
+    // Each preset writes to a scratch file; the final winner is copied to the
+    // output path atomically, so an abort never leaves a half-written PDF.
+    const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-pdf-opt-'));
+    try {
+        let smallestSize = Number.POSITIVE_INFINITY;
+        let smallestFile = '';
+        let smallestName = '';
+        for (const [index, preset] of PDF_PRESETS.entries()) {
+            if (ctx.signal?.aborted) {
+                throw new OptimizeError(convertError('cancelled', 'Optimization cancelled.'));
+            }
+            const attempt = path.join(tmpDir, `attempt-${index}.pdf`);
+            await execTool(gs, [...base, `-sOutputFile=${attempt}`, `-dPDFSETTINGS=${preset.setting}`, input], {
+                timeoutMs: ctx.timeoutMs,
+                signal: ctx.signal,
+            });
+            const size = (await fs.stat(attempt)).size;
+            if (size <= targetBytes) {
+                await fs.copyFile(attempt, output);
+                return { detail: `ghostscript ${preset.name}`, warnings: [] };
+            }
+            if (size < smallestSize) {
+                smallestSize = size;
+                smallestFile = attempt;
+                smallestName = preset.name;
+            }
+        }
+        // The screen preset (smallest) is still above the target; keep it with
+        // an honest warning.
+        await fs.copyFile(smallestFile, output);
+        return {
+            detail: 'ghostscript screen (72 dpi)',
+            warnings: [
+                `Even the lowest preset exceeds the target (${Math.round(smallestSize / 1024)} KB produced); the smallest result was kept.`,
+            ],
+        };
+    }
+    finally {
+        await fs.rm(tmpDir, { recursive: true, force: true }).catch(() => undefined);
+    }
+}
+async function requireBinary(resolve, dep, ctx) {
+    const resolved = await resolve(dep);
+    if (!resolved) {
+        throw new OptimizeError(convertError('missing_dependency', `Missing dependency: ${dep.displayName ?? dep.name}.`, {
+            missing: [dep],
+            hint: `Install hint (${process.platform}): ${dep.installHint[platformKey()]}`,
+        }));
+    }
+    void ctx;
+    return resolved;
+}
+function platformKey() {
+    return process.platform === 'win32' ? 'win32' : process.platform === 'darwin' ? 'darwin' : 'linux';
+}

package/lib/core/paths.d.ts

@@ -0,0 +1,11 @@
+import type { FormatId } from './types.js';
+/**
+ * Default output for a single-file conversion: next to the source file, same
+ * base name, canonical extension of the target format.
+ */
+export declare function defaultOutputPath(input: string, to: FormatId): string;
+/**
+ * Default output for a batch conversion: under outputDir, same base name.
+ * outputDir defaults to `<inputDir>/output` and is created by the caller.
+ */
+export declare function batchOutputPath(outputDir: string, input: string, to: FormatId): string;

package/lib/core/paths.js

@@ -0,0 +1,19 @@
+import path from 'node:path';
+import { canonicalExtension } from './formats.js';
+/**
+ * Default output for a single-file conversion: next to the source file, same
+ * base name, canonical extension of the target format.
+ */
+export function defaultOutputPath(input, to) {
+    const dir = path.dirname(input);
+    const base = path.basename(input, path.extname(input));
+    return path.join(dir, base + canonicalExtension(to));
+}
+/**
+ * Default output for a batch conversion: under outputDir, same base name.
+ * outputDir defaults to `<inputDir>/output` and is created by the caller.
+ */
+export function batchOutputPath(outputDir, input, to) {
+    const base = path.basename(input, path.extname(input));
+    return path.join(outputDir, base + canonicalExtension(to));
+}