dsh-file-convert 0.4.0

package/lib/core/converters/pdf.js

@@ -0,0 +1,316 @@
+import fs from 'node:fs/promises';
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { createRequire } from 'node:module';
+import './pdf-env.js';
+import { createCanvas } from '@napi-rs/canvas';
+import { getDocument } from 'pdfjs-dist/legacy/build/pdf.mjs';
+import { convertError } from '../errors.js';
+import { PageRangeError, parsePageRange } from '../utils/pages.js';
+import { OcrLanguageMissingError, OCR_LANGUAGE_DATA, TESSERACT, ocrLanguagesCached, resolveOcrEngine } from '../ocr.js';
+const require = createRequire(import.meta.url);
+/**
+ * Locate pdfjs-dist's standard_fonts directory so PDFs using the base-14
+ * (and similar) fonts render with correct glyphs. Best effort: rendering
+ * still works without it, some glyph substitutions may occur.
+ */
+function standardFontDataUrl() {
+    for (const target of ['pdfjs-dist/package.json', 'pdfjs-dist/build/pdf.mjs', 'pdfjs-dist']) {
+        let resolved;
+        try {
+            resolved = require.resolve(target);
+        }
+        catch {
+            continue;
+        }
+        let dir = path.dirname(resolved);
+        for (let i = 0; i < 5; i++) {
+            try {
+                const pkg = JSON.parse(readFileSync(path.join(dir, 'package.json'), 'utf8'));
+                if (pkg?.name === 'pdfjs-dist') {
+                    return pathToFileURL(path.join(dir, 'standard_fonts')).href + '/';
+                }
+            }
+            catch {
+                /* keep walking up */
+            }
+            const parent = path.dirname(dir);
+            if (parent === dir)
+                break;
+            dir = parent;
+        }
+    }
+    return undefined;
+}
+/**
+ * PDF conversions, fully local: rasterization via pdfjs-dist + @napi-rs/canvas
+ * (prebuilt npm binaries), text extraction via pdfjs-dist. No Poppler needed.
+ */
+export class PdfConverter {
+    resolve;
+    id = 'pdf';
+    concurrency = 2;
+    binaryDeps = [];
+    capabilities = [
+        { from: 'pdf', to: 'png' },
+        { from: 'pdf', to: 'jpg' },
+        { from: 'pdf', to: 'txt' },
+    ];
+    /** Optional binary resolver, needed only for OCR (Tesseract). */
+    constructor(resolve) {
+        this.resolve = resolve;
+    }
+    async convert(req, ctx) {
+        const started = Date.now();
+        try {
+            const bytesIn = (await fs.stat(req.input)).size;
+            const data = new Uint8Array(await fs.readFile(req.input));
+            const doc = (await getDocument({
+                data,
+                standardFontDataUrl: standardFontDataUrl(),
+                verbosity: 0,
+            }).promise);
+            try {
+                return req.to === 'txt'
+                    ? await this.toText(doc, req, ctx, bytesIn, started)
+                    : await this.toImages(doc, req, ctx, bytesIn, started);
+            }
+            finally {
+                await doc.cleanup().catch(() => undefined);
+            }
+        }
+        catch (err) {
+            if (err instanceof PageRangeError) {
+                return { ok: false, input: req.input, from: req.from, to: req.to, error: err.error };
+            }
+            return {
+                ok: false,
+                input: req.input,
+                from: req.from,
+                to: req.to,
+                error: convertError('conversion_failed', `Failed to convert ${req.from} → ${req.to}`, {
+                    detail: err instanceof Error ? err.message : String(err),
+                }),
+            };
+        }
+    }
+    /**
+     * Multi-page PDFs produce `<base>-<n>.<ext>` files named after the REAL page
+     * number; converting a single page (or a one-page PDF) writes exactly `output`.
+     */
+    async toImages(doc, req, ctx, bytesIn, started) {
+        const totalPages = doc.numPages;
+        const explicitSelection = Boolean(req.options.pages);
+        const selected = req.options.pages ? parsePageRange(req.options.pages, totalPages) : pageRange(totalPages);
+        const maxPdfPages = ctx.limits?.maxPdfPages;
+        if (!explicitSelection && maxPdfPages && totalPages > maxPdfPages) {
+            return failErr(req, convertError('invalid_input', `PDF has ${totalPages} pages, above the ${maxPdfPages}-page rasterization limit.`, {
+                hint: `Use pages (e.g. '1-${maxPdfPages}') to select, or raise 'maxPdfPages' in the plugin config.`,
+            }));
+        }
+        const scale = (req.options.dpi ?? 150) / 72; // PDFs have no intrinsic pixel size; 150 is a sane default.
+        const maxOutputPixels = ctx.limits?.maxOutputPixels;
+        let scaleReduced = false;
+        const pad = String(totalPages).length;
+        const outputs = [];
+        const warnings = [];
+        let bytesOut = 0;
+        for (const n of selected) {
+            if (ctx.signal?.aborted) {
+                return fail(req, 'cancelled', 'Conversion cancelled.');
+            }
+            const page = await doc.getPage(n);
+            try {
+                let renderScale = scale;
+                if (maxOutputPixels) {
+                    const viewport = page.getViewport({ scale });
+                    const pixels = viewport.width * viewport.height;
+                    if (pixels > maxOutputPixels) {
+                        renderScale = scale * Math.sqrt(maxOutputPixels / pixels);
+                        // ceil() on the viewport dims can nudge us just over the budget
+                        const cw = Math.ceil(viewport.width * (renderScale / scale));
+                        const ch = Math.ceil(viewport.height * (renderScale / scale));
+                        if (cw * ch > maxOutputPixels)
+                            renderScale *= maxOutputPixels / (cw * ch);
+                        scaleReduced = true;
+                    }
+                }
+                const buffer = await renderPage(page, renderScale, {
+                    background: req.to === 'jpg' ? req.options.background ?? '#ffffff' : undefined,
+                    quality: req.options.quality ?? 85,
+                    to: req.to,
+                });
+                const out = selected.length === 1 ? req.output : withPageNumber(req.output, n, pad);
+                await fs.writeFile(out, buffer);
+                bytesOut += buffer.byteLength;
+                outputs.push(out);
+            }
+            finally {
+                page.cleanup();
+            }
+        }
+        if (selected.length < totalPages) {
+            warnings.push(`Converted page(s) ${selected.join(', ')} of ${totalPages} (pages option).`);
+        }
+        else if (totalPages > 1) {
+            warnings.push(`PDF has ${totalPages} pages; wrote ${totalPages} files named <name>-<page>.${req.to}.`);
+        }
+        if (scaleReduced) {
+            warnings.push(`Raster scale was reduced on some pages to fit the pixel budget (maxOutputPixels).`);
+        }
+        return {
+            ok: true,
+            input: req.input,
+            output: outputs[0] ?? req.output,
+            outputs: outputs.length > 1 ? outputs : undefined,
+            from: req.from,
+            to: req.to,
+            bytesIn,
+            bytesOut,
+            durationMs: Date.now() - started,
+            warnings,
+        };
+    }
+    async toText(doc, req, ctx, bytesIn, started) {
+        const totalPages = doc.numPages;
+        const selected = req.options.pages ? parsePageRange(req.options.pages, totalPages) : pageRange(totalPages);
+        const warnings = [];
+        const pageTexts = [];
+        for (const n of selected) {
+            if (ctx.signal?.aborted) {
+                return fail(req, 'cancelled', 'Conversion cancelled.');
+            }
+            const page = await doc.getPage(n);
+            try {
+                const content = await page.getTextContent();
+                pageTexts.push(itemsToText(content.items));
+            }
+            finally {
+                page.cleanup();
+            }
+        }
+        if (req.options.ocr === true) {
+            if (!this.resolve) {
+                return failErr(req, convertError('conversion_failed', 'OCR is unavailable in this build (no binary resolver).'));
+            }
+            const engine = await resolveOcrEngine(this.resolve, ctx.logger);
+            if (!engine) {
+                return failErr(req, convertError('missing_dependency', 'OCR was requested but no OCR engine is available.', {
+                    missing: [TESSERACT],
+                    hint: `Install hint (${process.platform}): ${TESSERACT.installHint[platformKey()]} - or reinstall the plugin so its bundled tesseract.js fallback is present.`,
+                }));
+            }
+            const ocrLang = req.options.ocrLang ?? 'chi_sim+eng';
+            // The bundled engine needs language data that is NOT downloaded
+            // implicitly: without a cached pack we fail with guidance instead.
+            if (engine.name === 'tesseract.js' && !(await ocrLanguagesCached(ocrLang))) {
+                return failErr(req, convertError('missing_dependency', `OCR language data for '${ocrLang}' is not cached yet.`, {
+                    missing: [OCR_LANGUAGE_DATA],
+                    hint: 'Ask the agent to run install_ocr_dependencies (downloads about 10-30 MB per language into the plugin cache), or install a local Tesseract CLI and set tesseractPath if needed.',
+                }));
+            }
+            if (pageTexts.some((t) => t.trim().length > 0)) {
+                warnings.push('A text layer was detected; OCR was used anyway because ocr: true.');
+            }
+            // OCR needs legible pixels: default to a higher density than rasterization.
+            const scale = Math.max((req.options.dpi ?? 200) / 72, 200 / 72);
+            const ocrTexts = [];
+            for (const n of selected) {
+                if (ctx.signal?.aborted) {
+                    return fail(req, 'cancelled', 'Conversion cancelled.');
+                }
+                const page = await doc.getPage(n);
+                try {
+                    const png = await renderPage(page, scale, { to: 'png', quality: 100 });
+                    ocrTexts.push((await engine.recognizePng(png, ocrLang, ctx)).trim());
+                }
+                catch (err) {
+                    if (err instanceof OcrLanguageMissingError) {
+                        return failErr(req, convertError('missing_dependency', `The local Tesseract is missing language data for '${ocrLang}'.`, {
+                            hint: `Install the '${ocrLang}' traineddata for your Tesseract, or pick an ocr_lang it provides.`,
+                        }));
+                    }
+                    throw err;
+                }
+                finally {
+                    page.cleanup();
+                }
+            }
+            warnings.push(`OCR via ${engine.name} (${ocrLang}); quality depends on scan quality.`);
+            pageTexts.length = 0;
+            pageTexts.push(...ocrTexts);
+        }
+        else if (pageTexts.every((t) => t.trim().length === 0)) {
+            warnings.push('No extractable text found - this may be a scanned PDF. Re-run with ocr: true.');
+        }
+        const text = pageTexts.join('\n\n').replace(/\n{4,}/g, '\n\n\n') + '\n';
+        await fs.writeFile(req.output, text, 'utf8');
+        if (selected.length < totalPages) {
+            warnings.push(`Converted page(s) ${selected.join(', ')} of ${totalPages} (pages option).`);
+        }
+        return {
+            ok: true,
+            input: req.input,
+            output: req.output,
+            from: req.from,
+            to: req.to,
+            bytesIn,
+            bytesOut: Buffer.byteLength(text),
+            durationMs: Date.now() - started,
+            warnings,
+        };
+    }
+}
+function pageRange(totalPages) {
+    return Array.from({ length: totalPages }, (_, i) => i + 1);
+}
+/** Rasterize one page at a scale; white background for JPEG, transparent PNG otherwise. */
+async function renderPage(page, scale, opts) {
+    const viewport = page.getViewport({ scale });
+    const width = Math.max(1, Math.ceil(viewport.width));
+    const height = Math.max(1, Math.ceil(viewport.height));
+    const canvas = createCanvas(width, height);
+    const cctx = canvas.getContext('2d');
+    if (opts.background) {
+        cctx.fillStyle = opts.background;
+        cctx.fillRect(0, 0, width, height);
+    }
+    await page.render({ canvasContext: cctx, viewport }).promise;
+    return opts.to === 'png' ? canvas.encode('png') : canvas.encode('jpeg', opts.quality);
+}
+function fail(req, code, message) {
+    return { ok: false, input: req.input, from: req.from, to: req.to, error: convertError(code, message) };
+}
+function failErr(req, error) {
+    return { ok: false, input: req.input, from: req.from, to: req.to, error };
+}
+function platformKey() {
+    return process.platform === 'win32' ? 'win32' : process.platform === 'darwin' ? 'darwin' : 'linux';
+}
+/** Minimal per-page text assembly: keep line breaks, avoid word-gluing. */
+function itemsToText(items) {
+    const lines = [];
+    let line = '';
+    for (const item of items) {
+        const s = item.str;
+        if (s === undefined)
+            continue;
+        if (s.length > 0) {
+            if (line.length > 0 && !line.endsWith(' ') && !s.startsWith(' '))
+                line += ' ';
+            line += s;
+        }
+        if (item.hasEOL) {
+            lines.push(line.trimEnd());
+            line = '';
+        }
+    }
+    if (line.trimEnd().length > 0)
+        lines.push(line.trimEnd());
+    return lines.join('\n').trimEnd();
+}
+function withPageNumber(output, page, pad) {
+    const { dir, name, ext } = path.parse(output);
+    return path.join(dir, `${name}-${String(page).padStart(pad, '0')}${ext}`);
+}

package/lib/core/detect.d.ts

@@ -0,0 +1,16 @@
+import type { Detection } from './types.js';
+export interface DetectOutcome {
+    detection: Detection;
+    warnings: string[];
+}
+export declare class DetectError extends Error {
+    readonly error: import('./types.js').ConvertError;
+    constructor(error: import('./types.js').ConvertError);
+}
+/**
+ * Detect the format of a file. Priority: binary magic bytes (file-type) →
+ * SVG content → JSON content → extension → YAML document marker. When content
+ * and extension disagree, content wins and a warning is returned — users
+ * rename files wrongly all the time.
+ */
+export declare function detectFile(input: string): Promise<DetectOutcome>;

package/lib/core/detect.js

@@ -0,0 +1,121 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { fileTypeFromFile } from 'file-type';
+import { convertError } from './errors.js';
+import { formatFromExtension } from './formats.js';
+/** MIME types file-type can report that map 1:1 onto a supported format. */
+const MIME_TO_FORMAT = {
+    'image/png': 'png',
+    'image/jpeg': 'jpg',
+    'image/webp': 'webp',
+    'image/gif': 'gif',
+    'application/pdf': 'pdf',
+    'application/vnd.openxmlformats-officedocument.wordprocessingml.document': 'docx',
+    'application/vnd.openxmlformats-officedocument.presentationml.presentation': 'pptx',
+    'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet': 'xlsx',
+    'video/mp4': 'mp4',
+    'video/quicktime': 'mov',
+    'audio/mpeg': 'mp3',
+    'audio/wav': 'wav',
+    'audio/vnd.wave': 'wav',
+    'audio/x-wav': 'wav',
+};
+const TEXT_SNIFF_BYTES = 512;
+/** Whole-file JSON.parse is only attempted up to this size; larger files fall back to the extension. */
+const JSON_SNIFF_LIMIT = 1_000_000;
+const SVG_MIME = 'image/svg+xml';
+export class DetectError extends Error {
+    error;
+    constructor(error) {
+        super(error.message);
+        this.error = error;
+    }
+}
+/**
+ * Detect the format of a file. Priority: binary magic bytes (file-type) →
+ * SVG content → JSON content → extension → YAML document marker. When content
+ * and extension disagree, content wins and a warning is returned — users
+ * rename files wrongly all the time.
+ */
+export async function detectFile(input) {
+    const stat = await fs.stat(input).catch(() => null);
+    if (!stat) {
+        throw new DetectError(convertError('input_not_found', `Input file not found: ${input}`));
+    }
+    if (stat.isDirectory()) {
+        throw new DetectError(convertError('invalid_input', `Input is a directory, not a file: ${input}`));
+    }
+    const warnings = [];
+    const ext = path.extname(input).replace(/^\./, '');
+    const extFormat = ext ? formatFromExtension(ext) : null;
+    // 1. Binary formats via magic bytes.
+    const magic = await fileTypeFromFile(input).catch(() => undefined);
+    const magicFormat = magic ? MIME_TO_FORMAT[magic.mime] : undefined;
+    // 2. SVG is text-based; file-type does not report it.
+    const svgLike = magicFormat ? false : await looksLikeSvg(input);
+    const detected = magicFormat ?? (svgLike ? 'svg' : null);
+    if (detected) {
+        if (extFormat && extFormat !== detected) {
+            warnings.push(`File extension suggests ${extFormat} but content is ${detected}; using ${detected}.`);
+        }
+        return {
+            detection: { format: detected, confidence: 'magic', mime: magic?.mime ?? SVG_MIME },
+            warnings,
+        };
+    }
+    // 3. JSON parses successfully — essentially zero false positives when the
+    //    content starts with { or [ (scalars like `123` stay ambiguous).
+    if (await isJsonContent(input)) {
+        if (extFormat && extFormat !== 'json') {
+            warnings.push(`File extension suggests ${extFormat} but content parses as JSON; using json.`);
+        }
+        return { detection: { format: 'json', confidence: 'magic', mime: 'application/json' }, warnings };
+    }
+    // 4. Extension mapping (csv/txt cannot be told apart from plain text by content).
+    if (extFormat) {
+        return { detection: { format: extFormat, confidence: 'extension', mime: undefined }, warnings };
+    }
+    // 5. YAML document marker, for extension-less files only — a leading `---`
+    //    line is a strong YAML signal but not proof (markdown frontmatter, rules).
+    if (await startsWithYamlMarker(input)) {
+        return { detection: { format: 'yaml', confidence: 'guess', mime: 'application/yaml' }, warnings };
+    }
+    throw new DetectError(convertError('unknown_format', `Cannot determine the format of ${input}`, {
+        hint: 'inspect_file it first, or rename it with a known extension (png, jpg, webp, svg, pdf, json, yaml, csv, txt).',
+    }));
+}
+async function readHead(input, bytes) {
+    return fs.open(input, 'r').then(async (handle) => {
+        try {
+            const buffer = Buffer.alloc(bytes);
+            const { bytesRead } = await handle.read(buffer, 0, bytes, 0);
+            return buffer.subarray(0, bytesRead).toString('utf8').replace(/^\uFEFF/, '');
+        }
+        finally {
+            await handle.close();
+        }
+    }).catch(() => '');
+}
+async function looksLikeSvg(input) {
+    return (await readHead(input, TEXT_SNIFF_BYTES)).includes('<svg');
+}
+/** True when the whole file JSON-parses and starts with an unambiguous container. */
+async function isJsonContent(input) {
+    const stat = await fs.stat(input).catch(() => null);
+    if (!stat || stat.size === 0 || stat.size > JSON_SNIFF_LIMIT)
+        return false;
+    const text = await fs.readFile(input, 'utf8').catch(() => '');
+    const trimmed = text.trim();
+    if (!trimmed.startsWith('{') && !trimmed.startsWith('['))
+        return false;
+    try {
+        JSON.parse(trimmed);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function startsWithYamlMarker(input) {
+    return /^---\s*(\r?\n|$)/.test((await readHead(input, 64)).trimStart());
+}

package/lib/core/errors.d.ts

@@ -0,0 +1,5 @@
+import type { ConvertError, ConvertErrorCode } from './types.js';
+export declare function convertError(code: ConvertErrorCode, message: string, extra?: Partial<Omit<ConvertError, 'code' | 'message'>>): ConvertError;
+export declare function truncate(text: string, max?: number): string;
+/** Normalize an unknown thrown value into a ConvertError. */
+export declare function toConvertError(err: unknown, fallbackMessage: string): ConvertError;

package/lib/core/errors.js

@@ -0,0 +1,16 @@
+/** Detail output longer than this is truncated into ConvertError.detail. */
+const MAX_DETAIL = 2048;
+export function convertError(code, message, extra = {}) {
+    return { code, message, ...extra };
+}
+export function truncate(text, max = MAX_DETAIL) {
+    const clean = text.replace(/\s+/g, ' ').trim();
+    return clean.length <= max ? clean : clean.slice(0, max) + `… (+${clean.length - max} chars)`;
+}
+/** Normalize an unknown thrown value into a ConvertError. */
+export function toConvertError(err, fallbackMessage) {
+    if (err instanceof Error) {
+        return convertError('conversion_failed', fallbackMessage, { detail: truncate(err.stack ?? err.message) });
+    }
+    return convertError('conversion_failed', fallbackMessage, { detail: truncate(String(err)) });
+}

package/lib/core/formats.d.ts

@@ -0,0 +1,11 @@
+import type { FormatCategory, FormatId, FormatMeta } from './types.js';
+/** Single source of truth for format metadata. */
+export declare const FORMATS: Record<FormatId, FormatMeta>;
+export declare const FORMAT_IDS: FormatId[];
+/** Resolve a free-text format name ('JPEG', '.yml', 'webp') to a FormatId. */
+export declare function parseFormatArg(value: string): FormatId | null;
+/** Extension (without dot) → FormatId, e.g. 'jpeg' → 'jpg'. */
+export declare function formatFromExtension(ext: string): FormatId | null;
+/** Canonical output extension for a format, e.g. 'jpg' → '.jpg'. */
+export declare function canonicalExtension(format: FormatId): string;
+export declare function formatCategory(format: FormatId): FormatCategory;

package/lib/core/formats.js

@@ -0,0 +1,60 @@
+/** Single source of truth for format metadata. */
+export const FORMATS = {
+    pdf: { category: 'document', extensions: ['.pdf'], mime: 'application/pdf' },
+    docx: {
+        category: 'document',
+        extensions: ['.docx'],
+        mime: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+    },
+    pptx: {
+        category: 'document',
+        extensions: ['.pptx'],
+        mime: 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+    },
+    xlsx: {
+        category: 'document',
+        extensions: ['.xlsx'],
+        mime: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+    },
+    png: { category: 'image', extensions: ['.png'], mime: 'image/png' },
+    jpg: { category: 'image', extensions: ['.jpg', '.jpeg'], mime: 'image/jpeg' },
+    webp: { category: 'image', extensions: ['.webp'], mime: 'image/webp' },
+    svg: { category: 'image', extensions: ['.svg'], mime: 'image/svg+xml' },
+    gif: { category: 'image', extensions: ['.gif'], mime: 'image/gif' },
+    mp4: { category: 'video', extensions: ['.mp4'], mime: 'video/mp4' },
+    mov: { category: 'video', extensions: ['.mov'], mime: 'video/quicktime' },
+    mp3: { category: 'audio', extensions: ['.mp3'], mime: 'audio/mpeg' },
+    wav: { category: 'audio', extensions: ['.wav'], mime: 'audio/wav' },
+    json: { category: 'data', extensions: ['.json'], mime: 'application/json' },
+    yaml: { category: 'data', extensions: ['.yaml', '.yml'], mime: 'application/yaml' },
+    csv: { category: 'data', extensions: ['.csv'], mime: 'text/csv' },
+    txt: { category: 'text', extensions: ['.txt'], mime: 'text/plain' },
+};
+export const FORMAT_IDS = Object.keys(FORMATS);
+const EXT_TO_FORMAT = new Map();
+for (const [id, meta] of Object.entries(FORMATS)) {
+    for (const ext of meta.extensions)
+        EXT_TO_FORMAT.set(ext.slice(1).toLowerCase(), id);
+}
+/** Input aliases users (and agents) type instead of canonical ids. */
+const ALIASES = {
+    jpeg: 'jpg',
+    jpe: 'jpg',
+    yml: 'yaml',
+};
+/** Resolve a free-text format name ('JPEG', '.yml', 'webp') to a FormatId. */
+export function parseFormatArg(value) {
+    const key = value.trim().toLowerCase().replace(/^\./, '');
+    return ALIASES[key] ?? (key in FORMATS ? key : null);
+}
+/** Extension (without dot) → FormatId, e.g. 'jpeg' → 'jpg'. */
+export function formatFromExtension(ext) {
+    return EXT_TO_FORMAT.get(ext.toLowerCase()) ?? (ALIASES[ext.toLowerCase()] ?? null);
+}
+/** Canonical output extension for a format, e.g. 'jpg' → '.jpg'. */
+export function canonicalExtension(format) {
+    return FORMATS[format].extensions[0];
+}
+export function formatCategory(format) {
+    return FORMATS[format].category;
+}

package/lib/core/index.d.ts

@@ -0,0 +1,25 @@
+/**
+ * dsh-file-convert core: a DSH-independent conversion library.
+ * Usable directly from tests, a CLI, or an MCP server - no harness required.
+ */
+export * from './types.js';
+export { FORMATS, FORMAT_IDS, formatFromExtension, parseFormatArg, canonicalExtension, formatCategory } from './formats.js';
+export { ConversionRouter, type RouterDefaults, type ConvertFileRequest, type ConvertRunContext } from './router.js';
+export { detectFile, DetectError, type DetectOutcome } from './detect.js';
+export { resolveBinary } from './binary.js';
+export { defaultOutputPath, batchOutputPath } from './paths.js';
+export { ImageConverter } from './converters/image.js';
+export { PdfConverter } from './converters/pdf.js';
+export { DataConverter } from './converters/data.js';
+export { MediaConverter, FFMPEG, FFPROBE } from './converters/media.js';
+export { OfficeConverter, PdfToDocxConverter, SOFFICE, PYTHON_PDF2DOCX } from './converters/office.js';
+export { GHOSTSCRIPT } from './optimizers.js';
+export { TESSERACT, OCR_LANGUAGE_DATA, ocrLanguagesCached, installOcrLanguages, tessdataDir, resolveOcrEngine, type OcrEngine } from './ocr.js';
+export { parsePageRange, PageRangeError } from './utils/pages.js';
+export { optimizeFile, type OptimizeResult } from './optimizers.js';
+import { ConversionRouter, type RouterDefaults } from './router.js';
+/**
+ * Assemble the registry: image (sharp), pdf (pdfjs), data (yaml/csv),
+ * media (ffmpeg), office (LibreOffice), pdf→docx (python pdf2docx).
+ */
+export declare function createRouter(defaults?: Partial<RouterDefaults>): ConversionRouter;

package/lib/core/index.js

@@ -0,0 +1,52 @@
+/**
+ * dsh-file-convert core: a DSH-independent conversion library.
+ * Usable directly from tests, a CLI, or an MCP server - no harness required.
+ */
+export * from './types.js';
+export { FORMATS, FORMAT_IDS, formatFromExtension, parseFormatArg, canonicalExtension, formatCategory } from './formats.js';
+export { ConversionRouter } from './router.js';
+export { detectFile, DetectError } from './detect.js';
+export { resolveBinary } from './binary.js';
+export { defaultOutputPath, batchOutputPath } from './paths.js';
+export { ImageConverter } from './converters/image.js';
+export { PdfConverter } from './converters/pdf.js';
+export { DataConverter } from './converters/data.js';
+export { MediaConverter, FFMPEG, FFPROBE } from './converters/media.js';
+export { OfficeConverter, PdfToDocxConverter, SOFFICE, PYTHON_PDF2DOCX } from './converters/office.js';
+export { GHOSTSCRIPT } from './optimizers.js';
+export { TESSERACT, OCR_LANGUAGE_DATA, ocrLanguagesCached, installOcrLanguages, tessdataDir, resolveOcrEngine } from './ocr.js';
+export { parsePageRange, PageRangeError } from './utils/pages.js';
+export { optimizeFile } from './optimizers.js';
+import { ConversionRouter } from './router.js';
+import { ImageConverter } from './converters/image.js';
+import { PdfConverter } from './converters/pdf.js';
+import { DataConverter } from './converters/data.js';
+import { MediaConverter } from './converters/media.js';
+import { OfficeConverter, PdfToDocxConverter } from './converters/office.js';
+import { resolveBinary } from './binary.js';
+const SILENT_LOGGER = { debug() { }, info() { }, warn() { }, error() { } };
+/**
+ * Assemble the registry: image (sharp), pdf (pdfjs), data (yaml/csv),
+ * media (ffmpeg), office (LibreOffice), pdf→docx (python pdf2docx).
+ */
+export function createRouter(defaults) {
+    const overrides = defaults?.binaryOverrides ?? {};
+    const resolve = (dep) => resolveBinary(dep, overrides, SILENT_LOGGER);
+    const router = new ConversionRouter({
+        quality: defaults?.quality ?? 85,
+        dpi: defaults?.dpi ?? 150,
+        timeoutMs: defaults?.timeoutMs ?? 120_000,
+        outputRoots: defaults?.outputRoots,
+        binaryOverrides: overrides,
+        maxInputBytes: defaults?.maxInputBytes,
+        maxPdfPages: defaults?.maxPdfPages,
+        maxOutputPixels: defaults?.maxOutputPixels,
+    });
+    router.register(new ImageConverter());
+    router.register(new PdfConverter(resolve));
+    router.register(new DataConverter());
+    router.register(new MediaConverter(resolve));
+    router.register(new OfficeConverter(resolve));
+    router.register(new PdfToDocxConverter(resolve));
+    return router;
+}

package/lib/core/inspect.d.ts

@@ -0,0 +1,13 @@
+import './converters/pdf-env.js';
+import type { Detection, InspectResult } from './types.js';
+export interface MediaProbeContext {
+    ffprobePath: string;
+    timeoutMs: number;
+    signal?: AbortSignal;
+}
+/**
+ * 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 declare function inspectFile(input: string, detection: Detection, bytes: number, media?: MediaProbeContext): Promise<InspectResult>;