dsh-file-convert 0.4.0

package/lib/core/router.d.ts

@@ -0,0 +1,64 @@
+import { type DetectOutcome } from './detect.js';
+import type { ConvertResult, Converter, ConversionStatus, FormatId, InspectResult, Logger } from './types.js';
+export interface RouterDefaults {
+    /** Default JPEG/WebP quality (1-100). */
+    quality: number;
+    /** Default rasterization DPI for pdf/svg inputs. */
+    dpi: number;
+    /** Cooperative deadline for one conversion, in milliseconds. */
+    timeoutMs: number;
+    /**
+     * When non-empty, EXPLICIT output paths must resolve inside one of these
+     * directories (case-insensitive on Windows). Default output (next to the
+     * input) is exempt. Empty = unrestricted, which is fine for a personal
+     * single-user harness; set it for shared deployments.
+     */
+    outputRoots?: string[];
+    /** Config-key overrides for external binary resolution, e.g. ffmpegPath. */
+    binaryOverrides?: Record<string, string>;
+    /** Inputs larger than this are refused (bytes). Default 2 GiB. */
+    maxInputBytes?: number;
+    /** Full-document PDF rasterization refuses to exceed this page count. Default 200. */
+    maxPdfPages?: number;
+    /** Rasterized pixels per page are clamped to this. Default 16 MP. */
+    maxOutputPixels?: number;
+}
+export interface ConvertFileRequest {
+    input: string;
+    /** Free-text target format; aliases like 'jpeg' / '.yml' are accepted. */
+    outputFormat: string;
+    /** Absolute output path; defaults to next to the input file. */
+    output?: string;
+    overwrite?: boolean;
+    quality?: number;
+    dpi?: number;
+    /** One-based inclusive page selection for PDF inputs, e.g. '1-3,5'. */
+    pages?: string;
+    /** OCR the pages instead of reading the text layer (PDF → TXT). */
+    ocr?: boolean;
+    /** OCR languages, '+'-separated. Default 'chi_sim+eng'. */
+    ocrLang?: string;
+}
+export interface ConvertRunContext {
+    logger: Logger;
+    signal?: AbortSignal;
+}
+/**
+ * The facade every tool talks to. Owns the capability registry, detection,
+ * dependency checks, overwrite policy, and error normalization — converters
+ * only see well-formed requests.
+ */
+export declare class ConversionRouter {
+    private readonly defaults;
+    private readonly converters;
+    private readonly byPair;
+    constructor(defaults?: RouterDefaults);
+    register(converter: Converter): void;
+    detect(input: string): Promise<DetectOutcome>;
+    route(from: FormatId, to: FormatId): Converter | null;
+    /** The full matrix with dependency availability, for list_conversions. */
+    listConversions(): Promise<ConversionStatus[]>;
+    /** Full pipeline: detect → route → deps → overwrite policy → convert. */
+    convertFile(req: ConvertFileRequest, run: ConvertRunContext): Promise<ConvertResult>;
+    inspect(input: string): Promise<InspectResult>;
+}

package/lib/core/router.js

@@ -0,0 +1,288 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { convertError, toConvertError } from './errors.js';
+import { formatCategory, FORMAT_IDS, parseFormatArg } from './formats.js';
+import { detectFile, DetectError } from './detect.js';
+import { inspectFile } from './inspect.js';
+import { defaultOutputPath } from './paths.js';
+import { resolveBinary } from './binary.js';
+import { FFPROBE } from './converters/media.js';
+const DEFAULTS = { quality: 85, dpi: 150, timeoutMs: 120_000 };
+/**
+ * The facade every tool talks to. Owns the capability registry, detection,
+ * dependency checks, overwrite policy, and error normalization — converters
+ * only see well-formed requests.
+ */
+export class ConversionRouter {
+    defaults;
+    converters = new Map();
+    byPair = new Map();
+    constructor(defaults = DEFAULTS) {
+        this.defaults = defaults;
+    }
+    register(converter) {
+        if (this.converters.has(converter.id)) {
+            throw new Error(`Converter id already registered: ${converter.id}`);
+        }
+        this.converters.set(converter.id, converter);
+        for (const cap of converter.capabilities) {
+            let targets = this.byPair.get(cap.from);
+            if (!targets)
+                this.byPair.set(cap.from, (targets = new Map()));
+            if (targets.has(cap.to)) {
+                throw new Error(`Duplicate capability ${cap.from} -> ${cap.to} (${converter.id})`);
+            }
+            targets.set(cap.to, converter);
+        }
+    }
+    detect(input) {
+        return detectFile(input);
+    }
+    route(from, to) {
+        return this.byPair.get(from)?.get(to) ?? null;
+    }
+    /** The full matrix with dependency availability, for list_conversions. */
+    async listConversions() {
+        const statuses = [];
+        for (const converter of this.converters.values()) {
+            for (const cap of converter.capabilities) {
+                const missing = [];
+                for (const dep of converter.binaryDeps) {
+                    if (!(await resolveBinary(dep, this.defaults.binaryOverrides ?? {}, NULL_LOGGER)))
+                        missing.push(dep.name);
+                }
+                for (const name of cap.extraDeps ?? [])
+                    missing.push(name);
+                statuses.push({
+                    from: cap.from,
+                    to: cap.to,
+                    available: missing.length === 0,
+                    experimental: cap.experimental ?? false,
+                    missing,
+                });
+            }
+        }
+        statuses.sort((a, b) => (CATEGORY_RANK.get(a.from) ?? 0) - (CATEGORY_RANK.get(b.from) ?? 0) ||
+            a.from.localeCompare(b.from) ||
+            a.to.localeCompare(b.to));
+        return statuses;
+    }
+    /** Full pipeline: detect → route → deps → overwrite policy → convert. */
+    async convertFile(req, run) {
+        const to = parseFormatArg(req.outputFormat);
+        if (!to) {
+            const failure = convertError('unsupported_conversion', `Unknown output format '${req.outputFormat}'.`, { hint: `Supported formats: ${FORMAT_IDS.join(', ')}.` });
+            return { ok: false, input: req.input, error: failure };
+        }
+        try {
+            const inputStat = await fs.stat(req.input).catch(() => null);
+            if (inputStat?.isDirectory()) {
+                return {
+                    ok: false, input: req.input, to,
+                    error: convertError('invalid_input', `Input is a directory, not a file: ${req.input}`),
+                };
+            }
+            const maxInputBytes = this.defaults.maxInputBytes ?? 2 * 1024 ** 3;
+            if (inputStat && inputStat.size > maxInputBytes) {
+                const formatMb = (n) => `${Math.round(n / 1048576).toLocaleString('en-US')} MB`;
+                return {
+                    ok: false, input: req.input, to,
+                    error: convertError('invalid_input', `Input is ${formatMb(inputStat.size)}, above the ${formatMb(maxInputBytes)} limit.`, {
+                        hint: "Raise 'maxInputMb' in the plugin config, or convert in parts.",
+                    }),
+                };
+            }
+            const { detection, warnings } = await detectFile(req.input);
+            const from = detection.format;
+            if (from === to) {
+                return {
+                    ok: false, input: req.input, from, to,
+                    error: convertError('unsupported_conversion', `Input is already ${to}.`),
+                };
+            }
+            const converter = this.route(from, to);
+            if (!converter) {
+                return {
+                    ok: false, input: req.input, from, to,
+                    error: convertError('unsupported_conversion', `No conversion from ${from} to ${to}.`, {
+                        hint: 'Run list_conversions to see the supported matrix.',
+                    }),
+                };
+            }
+            const missing = await missingDeps(converter, this.defaults.binaryOverrides ?? {});
+            if (missing.length > 0) {
+                return {
+                    ok: false, input: req.input, from, to,
+                    error: convertError('missing_dependency', `Missing external dependency: ${missing.map((m) => m.name).join(', ')}.`, {
+                        missing,
+                        hint: `Install hint (${process.platform}): ${missing.map((m) => platformHint(m.installHint)).join('; ')}`,
+                    }),
+                };
+            }
+            const output = req.output ?? defaultOutputPath(req.input, to);
+            if (await isSameFile(output, req.input)) {
+                return {
+                    ok: false, input: req.input, from, to,
+                    error: convertError('invalid_input', 'Output path equals the input path; converting would destroy the source.', {
+                        hint: 'Choose a different output name or omit output to write next to the input with the new extension.',
+                    }),
+                };
+            }
+            if (req.output !== undefined && !(await isInsideRoots(output, this.defaults.outputRoots))) {
+                return {
+                    ok: false, input: req.input, from, to,
+                    error: convertError('invalid_input', `Output path ${output} is outside every configured outputRoot.`, {
+                        hint: `Allowed roots: ${this.defaults.outputRoots?.join(', ')}. Omit output to write next to the input.`,
+                    }),
+                };
+            }
+            await fs.mkdir(path.dirname(output), { recursive: true });
+            const overwrite = req.overwrite ?? false;
+            if (!overwrite && (await exists(output))) {
+                return {
+                    ok: false, input: req.input, from, to,
+                    error: convertError('output_exists', `Output file already exists: ${output}`, {
+                        hint: 'Pass overwrite: true to replace it.',
+                    }),
+                };
+            }
+            const options = {
+                overwrite,
+                // quality has one shared default; dpi semantics differ per backend
+                // (PDF rasterization vs SVG density), so converters apply their own.
+                quality: req.quality ?? this.defaults.quality,
+                dpi: req.dpi,
+                pages: req.pages,
+                ocr: req.ocr,
+                ocrLang: req.ocrLang,
+            };
+            const request = { input: req.input, output, from, to, options };
+            const ctx = {
+                logger: run.logger,
+                signal: run.signal,
+                timeoutMs: this.defaults.timeoutMs,
+                limits: { maxPdfPages: this.defaults.maxPdfPages, maxOutputPixels: this.defaults.maxOutputPixels },
+            };
+            const result = await withTimeout(converter.convert(request, ctx), ctx.timeoutMs, {
+                input: req.input, from, to,
+            });
+            if (result.ok)
+                result.warnings.unshift(...warnings);
+            return result;
+        }
+        catch (err) {
+            if (err instanceof DetectError) {
+                return { ok: false, input: req.input, to, error: err.error };
+            }
+            return {
+                ok: false,
+                input: req.input,
+                to,
+                error: toConvertError(err, `Conversion failed for ${req.input}`),
+            };
+        }
+    }
+    async inspect(input) {
+        const { detection } = await detectFile(input);
+        const bytes = (await fs.stat(input)).size;
+        let media;
+        if (detection.format === 'mp4' || detection.format === 'mov' || detection.format === 'mp3' || detection.format === 'wav') {
+            const ffprobe = await resolveBinary(FFPROBE, this.defaults.binaryOverrides ?? {}, NULL_LOGGER);
+            if (ffprobe) {
+                media = { ffprobePath: ffprobe, timeoutMs: Math.min(this.defaults.timeoutMs, 30_000) };
+            }
+        }
+        return inspectFile(input, detection, bytes, media);
+    }
+}
+/** Category ordering is static; compute the rank once instead of per sort call. */
+const CATEGORY_RANK = new Map([...FORMAT_IDS]
+    .sort((a, b) => formatCategory(a).localeCompare(formatCategory(b)))
+    .map((format, index) => [format, index]));
+/**
+ * realpath the deepest EXISTING ancestor of a path and rejoin the remainder:
+ * symlinks anywhere in the existing part are resolved, which is what
+ * outputRoots confinement needs (a symlink inside a root can point outside).
+ */
+async function realPathBestEffort(p) {
+    let current = path.resolve(p);
+    const tail = [];
+    for (;;) {
+        try {
+            return path.join(await fs.realpath(current), ...tail.reverse());
+        }
+        catch {
+            /* segment does not exist yet - walk up */
+        }
+        const parent = path.dirname(current);
+        if (parent === current)
+            return path.resolve(p);
+        tail.push(path.basename(current));
+        current = parent;
+    }
+}
+async function isSameFile(a, b) {
+    const ra = await realPathBestEffort(a);
+    const rb = await realPathBestEffort(b);
+    if (ra === rb)
+        return true;
+    // Windows paths are case-insensitive; also fold / vs \.
+    return process.platform === 'win32' && ra.replace(/\\/g, '/').toLowerCase() === rb.replace(/\\/g, '/').toLowerCase();
+}
+async function isInsideRoots(output, roots) {
+    if (!roots || roots.length === 0)
+        return true;
+    const candidate = await realPathBestEffort(output);
+    const normalized = process.platform === 'win32' ? candidate.replace(/\\/g, '/').toLowerCase() : candidate;
+    for (const root of roots) {
+        const prefix = await realPathBestEffort(path.resolve(root));
+        const normalizedPrefix = process.platform === 'win32' ? prefix.replace(/\\/g, '/').toLowerCase() : prefix;
+        if (normalized === normalizedPrefix ||
+            normalized.startsWith(normalizedPrefix.endsWith('/') ? normalizedPrefix : normalizedPrefix + '/')) {
+            return true;
+        }
+    }
+    return false;
+}
+async function missingDeps(converter, overrides) {
+    const missing = [];
+    for (const dep of converter.binaryDeps) {
+        if (!(await resolveBinary(dep, overrides, NULL_LOGGER)))
+            missing.push(dep);
+    }
+    return missing;
+}
+function platformHint(hint) {
+    return process.platform === 'win32' ? hint.win32 : process.platform === 'darwin' ? hint.darwin : hint.linux;
+}
+async function exists(path) {
+    try {
+        await fs.access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Cooperative deadline: long-running converters also observe ctx.signal. */
+async function withTimeout(promise, timeoutMs, meta) {
+    let timer;
+    const timeout = new Promise((resolve) => {
+        timer = setTimeout(() => {
+            resolve({
+                ok: false,
+                input: meta.input,
+                from: meta.from,
+                to: meta.to,
+                error: convertError('timeout', `Conversion exceeded ${Math.round(timeoutMs / 1000)}s and was abandoned.`),
+            });
+        }, timeoutMs);
+    });
+    try {
+        return await Promise.race([promise, timeout]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+const NULL_LOGGER = { debug() { }, info() { }, warn() { }, error() { } };

package/lib/core/types.d.ts

@@ -0,0 +1,199 @@
+/**
+ * Core type definitions for dsh-file-convert.
+ *
+ * This module (and everything under src/core) is deliberately independent of
+ * DeepSeek Harness / Cordis so it can be tested and reused without a running
+ * harness. The DSH glue layer lives in src/index.ts and src/tools/.
+ */
+export type FormatId = 'pdf' | 'docx' | 'pptx' | 'xlsx' | 'png' | 'jpg' | 'webp' | 'svg' | 'gif' | 'mp4' | 'mov' | 'mp3' | 'wav' | 'json' | 'yaml' | 'csv' | 'txt';
+export type FormatCategory = 'document' | 'image' | 'video' | 'audio' | 'data' | 'text';
+export interface FormatMeta {
+    category: FormatCategory;
+    /** Canonical extension first; used for default output naming. */
+    extensions: string[];
+    mime: string;
+}
+/** One declarative row of the conversion matrix. */
+export interface ConversionCapability {
+    from: FormatId;
+    to: FormatId;
+    /** Binaries needed by this specific row beyond the converter-level deps. */
+    extraDeps?: string[];
+    experimental?: boolean;
+}
+/**
+ * An external binary the plugin shells out to.
+ * Resolution order: config override → PATH → known install locations →
+ * plugin cache. `probe` allows deep checks (python with a specific module
+ * installed), `extraPaths` covers Windows installs that are not on PATH.
+ */
+export interface BinaryDependency {
+    name: string;
+    /** Name shown to users when this dependency is missing. */
+    displayName?: string;
+    /** Command names probed on PATH, e.g. ['ffmpeg']. */
+    commands: string[];
+    /** Plugin config key that overrides the resolved path, e.g. 'ffmpegPath'. */
+    configKey?: string;
+    /** Absolute locations probed when the command is not on PATH. */
+    extraPaths?: {
+        win32?: string[];
+        darwin?: string[];
+        linux?: string[];
+    };
+    /**
+     * Deep check run against the resolved path; false counts as missing
+     * (e.g. python present but the required package not importable).
+     * Results are memoized per (dependency, path) for the process lifetime.
+     */
+    probe?: (resolvedPath: string) => Promise<boolean>;
+    installHint: {
+        win32: string;
+        darwin: string;
+        linux: string;
+    };
+}
+export interface ConvertOptions {
+    overwrite: boolean;
+    /** 1-100, lossy targets (jpg/webp) only. */
+    quality?: number;
+    /** CSS color used to flatten alpha for non-alpha targets. Default '#ffffff'. */
+    background?: string;
+    /** Rasterization density for vector inputs (pdf/svg), in DPI. */
+    dpi?: number;
+    /** Indentation for json/yaml output. Default 2. */
+    indent?: number;
+    /** CSV delimiter. Default: sniffed from the first lines (, ; \t). */
+    delimiter?: string;
+    /** One-based inclusive page selection for PDF inputs, e.g. '1-3,5,8-10'. */
+    pages?: string;
+    /** OCR pages instead of reading the text layer (PDF → TXT). */
+    ocr?: boolean;
+    /** OCR languages, '+'-separated. Default 'chi_sim+eng'. */
+    ocrLang?: string;
+    /** Escape hatch for backend-specific options. */
+    extra?: Record<string, unknown>;
+}
+export interface ConvertRequest {
+    /** Absolute path to an existing file. */
+    input: string;
+    /** Absolute output path, already resolved by the caller. */
+    output: string;
+    from: FormatId;
+    to: FormatId;
+    options: ConvertOptions;
+}
+export type ConvertErrorCode = 'input_not_found' | 'unknown_format' | 'unsupported_conversion' | 'missing_dependency' | 'invalid_input' | 'output_exists' | 'conversion_failed' | 'timeout' | 'cancelled';
+export interface ConvertError {
+    code: ConvertErrorCode;
+    /** One human-readable line; agents relay this to the user verbatim. */
+    message: string;
+    /** Truncated stderr / decoder output for debugging. */
+    detail?: string;
+    missing?: BinaryDependency[];
+    hint?: string;
+}
+export type ConvertResult = {
+    ok: true;
+    input: string;
+    output: string;
+    from: FormatId;
+    to: FormatId;
+    bytesIn: number;
+    bytesOut: number;
+    durationMs: number;
+    warnings: string[];
+    /**
+     * Present when one input produced several outputs (multi-page PDF
+     * rasterization). Always includes `output` as the first entry.
+     */
+    outputs?: string[];
+} | {
+    ok: false;
+    input: string;
+    /** Absent when the input format could not be detected. */
+    from?: FormatId;
+    /** Absent when the requested output format was not parseable. */
+    to?: FormatId;
+    error: ConvertError;
+};
+export interface Logger {
+    debug(msg: string): void;
+    info(msg: string): void;
+    warn(msg: string): void;
+    error(msg: string): void;
+}
+export interface ConvertContext {
+    logger: Logger;
+    signal?: AbortSignal;
+    /** Hard deadline for a single conversion, in milliseconds. */
+    timeoutMs: number;
+    /** Resource ceilings applied to rasterization and page loops. */
+    limits?: {
+        /** Full-document PDF rasterization refuses to exceed this page count. */
+        maxPdfPages?: number;
+        /** Rasterized pixels per page (width × height) are clamped to this. */
+        maxOutputPixels?: number;
+    };
+}
+export interface Converter {
+    id: string;
+    capabilities: ConversionCapability[];
+    binaryDeps: BinaryDependency[];
+    /** Max parallel conversions for batch pools. 1 = must serialize. */
+    concurrency: number;
+    convert(req: ConvertRequest, ctx: ConvertContext): Promise<ConvertResult>;
+}
+export interface Detection {
+    format: FormatId;
+    /**
+     * 'magic' = decided by file content (binary magic, SVG/JSON sniffing);
+     * 'guess' = weak content heuristic (YAML document marker);
+     * 'extension' = decided by file name.
+     */
+    confidence: 'magic' | 'extension' | 'guess';
+    mime?: string;
+}
+export interface ConversionStatus {
+    from: FormatId;
+    to: FormatId;
+    available: boolean;
+    experimental: boolean;
+    /** Names of missing external binaries; empty when available. */
+    missing: string[];
+}
+export type InspectResult = {
+    kind: 'image';
+    format: FormatId;
+    width: number;
+    height: number;
+    channels?: number;
+    bytes: number;
+} | {
+    kind: 'pdf';
+    pages: number;
+    encrypted: boolean;
+    /** Heuristic: almost no extractable text → likely a scanned PDF. */
+    likelyScanned: boolean;
+    bytes: number;
+} | {
+    kind: 'media';
+    format: FormatId;
+    durationSec?: number;
+    width?: number;
+    height?: number;
+    fps?: number;
+    audioCodec?: string;
+    /** Present when ffprobe is missing; inspect degrades instead of failing. */
+    probeUnavailable?: boolean;
+    bytes: number;
+} | {
+    kind: 'data';
+    format: FormatId;
+    records?: number;
+    bytes: number;
+} | {
+    kind: 'unknown';
+    bytes: number;
+    mime?: string;
+};

package/lib/core/types.js

@@ -0,0 +1,8 @@
+/**
+ * Core type definitions for dsh-file-convert.
+ *
+ * This module (and everything under src/core) is deliberately independent of
+ * DeepSeek Harness / Cordis so it can be tested and reused without a running
+ * harness. The DSH glue layer lives in src/index.ts and src/tools/.
+ */
+export {};

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

@@ -0,0 +1,38 @@
+export interface ExecOptions {
+    /** Hard deadline in milliseconds; the child is killed when it fires. */
+    timeoutMs: number;
+    /** Cooperative cancellation from the harness (agent abort). */
+    signal?: AbortSignal;
+    /** Max stderr bytes kept for diagnostics. */
+    maxStderrBytes?: number;
+}
+export interface ExecOutcome {
+    code: number;
+    stdout: string;
+    stderr: string;
+}
+export declare class ExecError extends Error {
+    readonly code: 'timeout' | 'cancelled' | 'failed';
+    readonly stderr?: string | undefined;
+    constructor(code: 'timeout' | 'cancelled' | 'failed', message: string, stderr?: string | undefined);
+}
+/**
+ * Run an external tool, collecting stderr. Hardened for ffmpeg-style long
+ * jobs: no shell (array args), timeout kill, cooperative abort, capped
+ * stderr, hidden console window on Windows.
+ */
+export declare function execTool(command: string, args: string[], opts: ExecOptions): Promise<ExecOutcome>;
+/** ffprobe wrapper: one JSON document about the file's format and streams. */
+export declare function probeMedia(ffprobePath: string, input: string, timeoutMs: number, signal?: AbortSignal): Promise<MediaProbe | null>;
+export interface MediaProbe {
+    format?: {
+        duration?: string;
+    };
+    streams?: Array<{
+        codec_type?: string;
+        codec_name?: string;
+        width?: number;
+        height?: number;
+        r_frame_rate?: string;
+    }>;
+}

package/lib/core/utils/exec.js

@@ -0,0 +1,89 @@
+import { spawn } from 'node:child_process';
+import { truncate } from '../errors.js';
+export class ExecError extends Error {
+    code;
+    stderr;
+    constructor(code, message, stderr) {
+        super(message);
+        this.code = code;
+        this.stderr = stderr;
+    }
+}
+/**
+ * Run an external tool, collecting stderr. Hardened for ffmpeg-style long
+ * jobs: no shell (array args), timeout kill, cooperative abort, capped
+ * stderr, hidden console window on Windows.
+ */
+export function execTool(command, args, opts) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(command, args, {
+            windowsHide: true,
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        let settled = false;
+        const stderrCap = opts.maxStderrBytes ?? 64 * 1024;
+        let stderrBytes = 0;
+        const stderrChunks = [];
+        const stdoutChunks = [];
+        let timer;
+        const onAbort = () => {
+            if (!settled)
+                child.kill('SIGKILL');
+        };
+        const finish = (fn) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            opts.signal?.removeEventListener('abort', onAbort);
+            fn();
+        };
+        if (opts.signal) {
+            if (opts.signal.aborted) {
+                child.kill('SIGKILL');
+                return finish(() => reject(new ExecError('cancelled', 'Conversion cancelled.')));
+            }
+            opts.signal.addEventListener('abort', onAbort);
+        }
+        timer = setTimeout(() => {
+            child.kill('SIGKILL');
+            finish(() => reject(new ExecError('timeout', `External tool timed out after ${Math.round(opts.timeoutMs / 1000)}s: ${command}`, Buffer.concat(stderrChunks).toString('utf8'))));
+        }, opts.timeoutMs);
+        child.stderr.on('data', (chunk) => {
+            if (stderrBytes >= stderrCap)
+                return;
+            stderrChunks.push(chunk);
+            stderrBytes += chunk.length;
+        });
+        child.stdout.on('data', (chunk) => {
+            stdoutChunks.push(chunk);
+        });
+        child.on('error', (err) => {
+            finish(() => reject(new ExecError('failed', `Failed to run ${command}: ${err.message}`)));
+        });
+        child.on('close', (code, signal) => {
+            const stderr = Buffer.concat(stderrChunks).toString('utf8');
+            const stdout = Buffer.concat(stdoutChunks).toString('utf8');
+            if (opts.signal?.aborted) {
+                return finish(() => reject(new ExecError('cancelled', 'Conversion cancelled.', stderr)));
+            }
+            if (signal) {
+                return finish(() => reject(new ExecError('timeout', `External tool was killed (${signal}): ${command}`, truncate(stderr))));
+            }
+            if (code !== 0) {
+                return finish(() => reject(new ExecError('failed', `${command} exited with code ${code}`, truncate(stderr))));
+            }
+            finish(() => resolve({ code: code ?? 0, stdout, stderr }));
+        });
+    });
+}
+/** ffprobe wrapper: one JSON document about the file's format and streams. */
+export async function probeMedia(ffprobePath, input, timeoutMs, signal) {
+    try {
+        const { stdout } = await execTool(ffprobePath, ['-v', 'error', '-print_format', 'json', '-show_format', '-show_streams', input], { timeoutMs, signal, maxStderrBytes: 8 * 1024 });
+        return JSON.parse(stdout);
+    }
+    catch {
+        return null;
+    }
+}