dsh-file-convert 0.4.0 → 0.4.1

package/README.md

@@ -54,6 +54,12 @@ dsh plugin --profile default add github:zzy-12345678/dsh-file-convert
 ```
 
 Git installs may ask you to allow the build step in the profile's `pnpm-workspace.yaml`:
+> **First-install note**: pnpm may also ask you to decide on a build script for `tesseract.js` (it only shows a donation notice — skipping is safe). Set it in the same file and re-run the install:
+>
+> ```yaml
+> allowBuilds:
+>   tesseract.js: false
+> ```
 
 ```yaml
 allowBuilds:
@@ -163,6 +169,8 @@ All 26 conversions with their live availability on *this* machine — unavailabl
 | `maxInputMb` | `2048` | Refuse inputs above this size (MB) |
 | `maxPdfPages` | `200` | Full-document PDF rasterization refuses more pages; use `pages` for larger documents |
 | `maxOutputPixels` | `16000000` | Clamp rasterized pixels per page (width × height) to this budget |
+
+**Limit coverage**: `maxInputMb` applies to convert, batch, inspect and optimize alike; `maxPdfPages` applies to PDF rasterization and text extraction (both implicit full-document runs and explicit `pages` selections); `maxOutputPixels` applies to PDF rasterization, OCR rendering and SVG rasterization; `timeoutMs` truly cancels every conversion (the underlying work stops, it is not merely abandoned).
 | `batchMaxFiles` | `500` | Max files examined per `batch_convert` run; beyond it the summary reports what was skipped instead of silently capping |
 | `outputRoots` | `[]` | When non-empty, explicit `output` paths must resolve inside one of these directories (recommended for shared deployments; the default next-to-input output is always exempt) |
 | `ffmpegPath` / `ffprobePath` | - | Explicit binary paths when ffmpeg is not on PATH (common on Windows) |
@@ -201,7 +209,7 @@ All 26 conversions with their live availability on *this* machine — unavailabl
 ```sh
 npm install
 npm run build     # tsc -> lib/
-npm test          # vitest, 31 tests
+npm test          # vitest, 63 tests (plus a few environment-gated suites)
 npm run smoke     # end-to-end against lib/
 ```
 
@@ -213,6 +221,17 @@ Add a conversion = add one capability row + implement it in a converter. Add a b
 - **Cached ffmpeg builds**: the download convenience installs pinned sha256-verified FFmpeg 6.1.1 static builds. For untrusted media, a current system FFmpeg takes priority — prefer it in security-sensitive setups.
 - **Not a sandbox**: `outputRoots` resolves symlinks and resource limits (`maxInputMb`, `maxPdfPages`, `maxOutputPixels`, `batchMaxFiles`) cap runaway jobs, but the default next-to-input output is intentionally exempt from roots, and an agent that may write files can always write somewhere. For hostile multi-tenant use, add OS-level isolation on top.
 
+## Compatibility
+
+| Component | Verified version |
+| --- | --- |
+| DeepSeek Harness | 0.1.1-rc.2 |
+| @deepseek-ai/dsh-tools | 0.0.1-rc.1 |
+| @deepseek-ai/cordis | 4.0.1 |
+| Node.js | >= 20 (CI covers 22) |
+
+DSH is a developer preview and its APIs will move - the plugin keeps all DSH imports inside a thin glue layer so adapting stays cheap.
+
 ## Roadmap
 
 - ~~V0.2 — Media (FFmpeg)~~ **shipped**: MP4→GIF/MP3, WAV→MP3, MOV→MP4, plus `optimize_file` with target-size two-pass encoding.

package/README.zh-CN.md

@@ -54,6 +54,14 @@ dsh plugin --profile default add github:zzy-12345678/dsh-file-convert
 ```
 
 Git 安装可能需要在 profile 的 `pnpm-workspace.yaml` 里放行构建步骤：
+> **首次安装提示**：pnpm 还可能要求你决定 `tesseract.js` 的构建脚本是否执行（它只是捐赠提示，跳过毫无影响）。在同一个文件里加上：
+>
+> ```yaml
+> allowBuilds:
+>   tesseract.js: false
+> ```
+>
+> 然后重新执行安装命令即可。
 
 ```yaml
 allowBuilds:
@@ -121,7 +129,7 @@ PDF 走 Ghostscript 三档预设（printer/ebook/screen）自动迭代：某档
 
 下载固定的 FFmpeg 6.1.1 静态构建（ffmpeg + ffprobe 两个 ~28 MB 文件）到插件缓存（`~/.dsh-file-convert/bin`），校验钉死的 sha256，并真实执行一次二进制确认可用后才报告成功。npmmirror 二进制 CDN 优先，GitHub release 为字节一致的回退源。系统安装的 ffmpeg 优先于缓存。体积可观，调用前请先征得用户同意。
 
-默认从 `npmmirror.com` 镜像下载固定版本的 `@ffmpeg-installer` / `@ffprobe-installer` 二进制到插件缓存（`~/.dsh-file-convert/bin`），校验 sha512 完整性，并真实执行一次二进制确认可用后才报告成功（npmjs.org 自动回退，`registry` 参数可指定其它源）。系统安装的 ffmpeg 优先于缓存。体积可观，调用前请先征得用户同意。
+下载钉死 sha256 的 FFmpeg 6.1.1 静态构建（ffmpeg + ffprobe，各 ~28 MB）到插件缓存（`~/.dsh-file-convert/bin`），并真实执行一次二进制确认可用后才报告成功。npmmirror 二进制 CDN 优先，GitHub release 为字节一致的回退源。系统安装的 ffmpeg 优先于缓存。体积可观，调用前请先征得用户同意。
 
 ### `install_ocr_dependencies` —— 一键补齐 OCR 语言包
 
@@ -141,6 +149,8 @@ PDF 走 Ghostscript 三档预设（printer/ebook/screen）自动迭代：某档
 | `maxInputMb` | `2048` | 拒绝超过此大小（MB）的输入 |
 | `maxPdfPages` | `200` | 整本 PDF 光栅化超过此页数即拒绝；更大的文档请用 `pages` 选择 |
 | `maxOutputPixels` | `16000000` | 每页光栅化像素（宽 × 高）钳制到此预算 |
+
+**限制覆盖范围**：`maxInputMb` 作用于 convert / batch / inspect / optimize 全部入口；`maxPdfPages` 作用于 PDF 光栅化与文本提取（隐式整本与显式 `pages` 选择都受限）；`maxOutputPixels` 作用于 PDF 光栅化、OCR 渲染和 SVG 光栅化；`timeoutMs` 对所有转换真取消（超时会中止底层工作，不只是提前返回）。
 | `batchMaxFiles` | `500` | 每次 `batch_convert` 最多检查的文件数；超出时会在结果里明确报告跳过了多少，而不是静默截断 |
 | `outputRoots` | `[]` | 非空时，显式指定的 `output` 路径必须落在这些目录之内（共享部署建议开启；默认写到输入文件旁的输出不受限） |
 | `ffmpegPath` / `ffprobePath` | - | ffmpeg 不在 PATH 时（Windows 常见）手动指定二进制路径 |
@@ -179,7 +189,7 @@ PDF 走 Ghostscript 三档预设（printer/ebook/screen）自动迭代：某档
 ```sh
 npm install
 npm run build     # tsc -> lib/
-npm test          # vitest，31 个测试
+npm test          # vitest，63 项测试（另有个位数按环境门控的套件）
 npm run smoke     # 针对 lib/ 的端到端冒烟测试
 ```
 
@@ -191,6 +201,17 @@ npm run smoke     # 针对 lib/ 的端到端冒烟测试
 - **缓存版 ffmpeg**：便捷下载安装的是钉死 sha256 的 FFmpeg 6.1.1 静态构建。处理不可信媒体时，新版系统 FFmpeg 优先——安全敏感场景请优先系统安装。
 - **不是沙箱**：`outputRoots` 会解析符号链接，资源上限（`maxInputMb`、`maxPdfPages`、`maxOutputPixels`、`batchMaxFiles`）能拦住失控任务，但默认"写到输入文件旁"的输出有意不受 roots 约束，且能写文件的 Agent 总能找到地方写。敌对多租户场景请在操作系统层再加隔离。
 
+## 兼容性
+
+| 组件 | 已验证版本 |
+| --- | --- |
+| DeepSeek Harness | 0.1.1-rc.2 |
+| @deepseek-ai/dsh-tools | 0.0.1-rc.1 |
+| @deepseek-ai/cordis | 4.0.1 |
+| Node.js | ≥ 20（CI 覆盖 22） |
+
+DSH 仍处于 developer preview，API 可能变化——插件把 DSH 依赖隔离在薄胶水层，适配成本被刻意压低。
+
 ## Roadmap
 
 - ~~V0.2 —— 音视频（FFmpeg）~~ **已发布**：MP4→GIF/MP3、WAV→MP3、MOV→MP4，以及按目标体积两遍编码的 `optimize_file`。

package/lib/core/binaries/download.d.ts

@@ -19,3 +19,12 @@ export declare function downloadBinary(dep: BinaryDependency, opts: {
     signal?: AbortSignal;
     force?: boolean;
 }): Promise<DownloadOutcome>;
+export interface CacheManifestEntry {
+    version: string;
+    sha256: string;
+    bytes: number;
+    installedAt: string;
+}
+export type CacheManifest = Record<string, CacheManifestEntry>;
+export declare function manifestPath(): string;
+export declare function readCacheManifest(): Promise<CacheManifest>;

package/lib/core/binaries/download.js

@@ -7,7 +7,8 @@ import { Readable } from 'node:stream';
 import { pipeline } from 'node:stream/promises';
 import { createWriteStream } from 'node:fs';
 import { execTool } from '../utils/exec.js';
-import { cachedBinaryPath } from './cache.js';
+import { writeFileAtomic } from '../utils/write-file.js';
+import { cachedBinaryPath, cacheDir } from './cache.js';
 /**
  * Where each external binary comes from when the machine has none: pinned
  * single-binary FFmpeg 6.1.1 builds from the ffmpeg-static project, served by
@@ -88,12 +89,24 @@ export async function downloadBinary(dep, opts) {
             const gzPath = path.join(tmpDir, 'bin.gz');
             const bytes = await downloadTo(url, gzPath, opts.timeoutMs, opts.signal);
             verifyDigest(await fs.readFile(gzPath), entry.sha256);
-            await fs.mkdir(path.dirname(target), { recursive: true });
-            await fs.writeFile(target, gunzipSync(await fs.readFile(gzPath)));
+            // Prove the binary inside the scratch dir first, then publish it into
+            // the cache - a failed download never leaves a half-written target.
+            const candidate = path.join(tmpDir, 'bin');
+            await fs.writeFile(candidate, gunzipSync(await fs.readFile(gzPath)));
             if (process.platform !== 'win32')
-                await fs.chmod(target, 0o755);
-            const { stdout, stderr } = await execTool(target, ['-version'], { timeoutMs: 15_000, signal: opts.signal });
+                await fs.chmod(candidate, 0o755);
+            const { stdout, stderr } = await execTool(candidate, ['-version'], { timeoutMs: 15_000, signal: opts.signal });
             const versionLine = (stdout || stderr).split(/\r?\n/, 1)[0]?.trim() ?? '';
+            await fs.mkdir(path.dirname(target), { recursive: true });
+            await fs.rename(candidate, target).catch(async () => {
+                await fs.copyFile(candidate, target);
+            });
+            await writeManifestEntry(dep.name, {
+                version: versionLine,
+                sha256: entry.sha256,
+                bytes,
+                installedAt: new Date().toISOString(),
+            });
             return { path: target, bytes, versionLine };
         }
         catch (err) {
@@ -106,6 +119,22 @@ export async function downloadBinary(dep, opts) {
     }
     throw new DownloadError('network', `All mirrors failed for ${dep.name}: ${errors.join(' | ')}`);
 }
+export function manifestPath() {
+    return path.join(cacheDir(), 'manifest.json');
+}
+export async function readCacheManifest() {
+    try {
+        return JSON.parse(await fs.readFile(manifestPath(), 'utf8'));
+    }
+    catch {
+        return {};
+    }
+}
+async function writeManifestEntry(name, entry) {
+    const manifest = await readCacheManifest();
+    manifest[name] = entry;
+    await writeFileAtomic(manifestPath(), JSON.stringify(manifest, null, 2));
+}
 async function downloadTo(url, target, timeoutMs, signal) {
     let res;
     try {

package/lib/core/converters/data.js

@@ -2,6 +2,7 @@ import fs from 'node:fs/promises';
 import { parse as csvParse } from 'csv-parse/sync';
 import { stringify as csvStringify } from 'csv-stringify/sync';
 import yaml from 'js-yaml';
+import { writeFileAtomic } from '../utils/write-file.js';
 import { convertError } from '../errors.js';
 /**
  * JSON / YAML / CSV share one intermediate representation (a plain JS value):
@@ -39,7 +40,7 @@ export class DataConverter {
             const bytesIn = Buffer.byteLength(raw);
             const value = this.read(from, raw, req.options.delimiter);
             const text = this.write(to, value, req.options.indent);
-            await fs.writeFile(req.output, text, 'utf8');
+            await writeFileAtomic(req.output, text);
             return {
                 ok: true,
                 input: req.input,

package/lib/core/converters/image.js

@@ -1,5 +1,6 @@
 import fs from 'node:fs/promises';
 import sharp from 'sharp';
+import { writeFileAtomic } from '../utils/write-file.js';
 import { convertError } from '../errors.js';
 const IMAGE_INPUTS = ['png', 'jpg', 'webp', 'svg'];
 const IMAGE_OUTPUTS = ['png', 'jpg', 'webp'];
@@ -21,7 +22,20 @@ export class ImageConverter {
             const bytesIn = (await fs.stat(req.input)).size;
             // density only affects vector input (SVG): 72 renders at the SVG's own
             // pixel size; a higher dpi option upscales. Rasters ignore it.
-            const pipeline = sharp(req.input, { density: req.options.dpi ?? 72 });
+            // A hostile SVG can declare enormous dimensions - clamp the raster to
+            // the pixel budget before decoding.
+            let density = req.options.dpi ?? 72;
+            const maxOutputPixels = ctx.limits?.maxOutputPixels;
+            if (req.from === 'svg' && maxOutputPixels) {
+                const meta = await sharp(req.input).metadata();
+                const factor = density / 72;
+                const pixels = (meta.width ?? 1000) * factor * ((meta.height ?? 1000) * factor);
+                if (pixels > maxOutputPixels) {
+                    const shrink = Math.sqrt(maxOutputPixels / pixels);
+                    density = Math.max(1, Math.floor(density * shrink));
+                }
+            }
+            const pipeline = sharp(req.input, { density });
             const { quality, background } = req.options;
             let out;
             if (req.to === 'jpg') {
@@ -35,8 +49,9 @@ export class ImageConverter {
             else {
                 out = pipeline.png();
             }
-            await out.toFile(req.output);
-            const bytesOut = (await fs.stat(req.output)).size;
+            const buffer = await out.toBuffer();
+            await writeFileAtomic(req.output, buffer);
+            const bytesOut = buffer.length;
             return {
                 ok: true,
                 input: req.input,

package/lib/core/converters/office.js

@@ -174,12 +174,24 @@ export class PdfToDocxConverter {
             const bytesIn = (await fs.stat(req.input)).size;
             // pdf2docx has no __main__ module and its console script may not be on
             // PATH - drive the library API directly through the resolved interpreter.
-            await execTool(python, [
-                '-c', 'import sys; from pdf2docx import parse; parse(sys.argv[1], sys.argv[2])',
-                req.input, req.output,
-            ], { timeoutMs: ctx.timeoutMs, signal: ctx.signal });
-            if (!(await exists(req.output))) {
-                return fail(req, convertError('conversion_failed', 'pdf2docx reported success but produced no file.'));
+            // It writes its output directly, so use a scratch file in the output's
+            // own directory and only publish a complete document under the real name.
+            const scratch = path.join(path.dirname(req.output), `.${path.basename(req.output)}.${Date.now()}.tmp`);
+            try {
+                await execTool(python, [
+                    '-c', 'import sys; from pdf2docx import parse; parse(sys.argv[1], sys.argv[2])',
+                    req.input, scratch,
+                ], { timeoutMs: ctx.timeoutMs, signal: ctx.signal });
+                if (!(await exists(scratch))) {
+                    return fail(req, convertError('conversion_failed', 'pdf2docx reported success but produced no file.'));
+                }
+                await fs.rename(scratch, req.output).catch(async () => {
+                    await fs.copyFile(scratch, req.output);
+                    await fs.rm(scratch, { force: true });
+                });
+            }
+            finally {
+                await fs.rm(scratch, { force: true }).catch(() => undefined);
             }
             return {
                 ok: true,

package/lib/core/converters/pdf.js

@@ -8,6 +8,7 @@ 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 { writeFileAtomic } from '../utils/write-file.js';
 import { OcrLanguageMissingError, OCR_LANGUAGE_DATA, TESSERACT, ocrLanguagesCached, resolveOcrEngine } from '../ocr.js';
 const require = createRequire(import.meta.url);
 /**
@@ -109,6 +110,11 @@ export class PdfConverter {
                 hint: `Use pages (e.g. '1-${maxPdfPages}') to select, or raise 'maxPdfPages' in the plugin config.`,
             }));
         }
+        if (explicitSelection && maxPdfPages && selected.length > maxPdfPages) {
+            return failErr(req, convertError('invalid_input', `${selected.length} pages selected, above the ${maxPdfPages}-page rasterization limit.`, {
+                hint: `Narrow the pages selection 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;
@@ -142,10 +148,16 @@ export class PdfConverter {
                     to: req.to,
                 });
                 const out = selected.length === 1 ? req.output : withPageNumber(req.output, n, pad);
-                await fs.writeFile(out, buffer);
+                await writeFileAtomic(out, buffer);
                 bytesOut += buffer.byteLength;
                 outputs.push(out);
             }
+            catch (err) {
+                // all-or-nothing: a failed page removes the pages already written
+                for (const written of outputs)
+                    await fs.rm(written, { force: true }).catch(() => undefined);
+                throw err;
+            }
             finally {
                 page.cleanup();
             }
@@ -174,7 +186,19 @@ export class PdfConverter {
     }
     async toText(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 text-extraction limit.`, {
+                hint: `Use pages (e.g. '1-${maxPdfPages}') to select, or raise 'maxPdfPages' in the plugin config.`,
+            }));
+        }
+        if (explicitSelection && maxPdfPages && selected.length > maxPdfPages) {
+            return failErr(req, convertError('invalid_input', `${selected.length} pages selected, above the ${maxPdfPages}-page text-extraction limit.`, {
+                hint: `Narrow the pages selection or raise 'maxPdfPages' in the plugin config.`,
+            }));
+        }
         const warnings = [];
         const pageTexts = [];
         for (const n of selected) {
@@ -215,6 +239,7 @@ export class PdfConverter {
             }
             // OCR needs legible pixels: default to a higher density than rasterization.
             const scale = Math.max((req.options.dpi ?? 200) / 72, 200 / 72);
+            const maxOutputPixels = ctx.limits?.maxOutputPixels;
             const ocrTexts = [];
             for (const n of selected) {
                 if (ctx.signal?.aborted) {
@@ -222,7 +247,18 @@ export class PdfConverter {
                 }
                 const page = await doc.getPage(n);
                 try {
-                    const png = await renderPage(page, scale, { to: 'png', quality: 100 });
+                    let renderScale = scale;
+                    if (maxOutputPixels) {
+                        const viewport = page.getViewport({ scale });
+                        const pixels = viewport.width * viewport.height;
+                        if (pixels > maxOutputPixels) {
+                            // Recognition quality suffers on tiny rasters, so clamp gently
+                            // (2x the pixel budget) and say so.
+                            renderScale = scale * Math.sqrt((maxOutputPixels * 2) / pixels);
+                            warnings.push('OCR render scale was reduced on some pages to fit the pixel budget; recognition quality may drop.');
+                        }
+                    }
+                    const png = await renderPage(page, renderScale, { to: 'png', quality: 100 });
                     ocrTexts.push((await engine.recognizePng(png, ocrLang, ctx)).trim());
                 }
                 catch (err) {
@@ -245,7 +281,7 @@ export class PdfConverter {
             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');
+        await writeFileAtomic(req.output, text);
         if (selected.length < totalPages) {
             warnings.push(`Converted page(s) ${selected.join(', ')} of ${totalPages} (pages option).`);
         }

package/lib/core/index.d.ts

@@ -8,6 +8,8 @@ export { ConversionRouter, type RouterDefaults, type ConvertFileRequest, type Co
 export { detectFile, DetectError, type DetectOutcome } from './detect.js';
 export { resolveBinary } from './binary.js';
 export { defaultOutputPath, batchOutputPath } from './paths.js';
+export { isInsideAnyRoot, isInsideRoot, isSameFile, realPathBestEffort } from './utils/path-guard.js';
+export { writeFileAtomic } from './utils/write-file.js';
 export { ImageConverter } from './converters/image.js';
 export { PdfConverter } from './converters/pdf.js';
 export { DataConverter } from './converters/data.js';

package/lib/core/index.js

@@ -8,6 +8,8 @@ export { ConversionRouter } from './router.js';
 export { detectFile, DetectError } from './detect.js';
 export { resolveBinary } from './binary.js';
 export { defaultOutputPath, batchOutputPath } from './paths.js';
+export { isInsideAnyRoot, isInsideRoot, isSameFile, realPathBestEffort } from './utils/path-guard.js';
+export { writeFileAtomic } from './utils/write-file.js';
 export { ImageConverter } from './converters/image.js';
 export { PdfConverter } from './converters/pdf.js';
 export { DataConverter } from './converters/data.js';

package/lib/core/router.js

@@ -5,6 +5,7 @@ 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 { isInsideAnyRoot, isSameFile } from './utils/path-guard.js';
 import { resolveBinary } from './binary.js';
 import { FFPROBE } from './converters/media.js';
 const DEFAULTS = { quality: 85, dpi: 150, timeoutMs: 120_000 };
@@ -128,7 +129,7 @@ export class ConversionRouter {
                     }),
                 };
             }
-            if (req.output !== undefined && !(await isInsideRoots(output, this.defaults.outputRoots))) {
+            if (req.output !== undefined && !(await isInsideAnyRoot(output, this.defaults.outputRoots))) {
                 return {
                     ok: false, input: req.input, from, to,
                     error: convertError('invalid_input', `Output path ${output} is outside every configured outputRoot.`, {
@@ -157,18 +158,41 @@ export class ConversionRouter {
                 ocrLang: req.ocrLang,
             };
             const request = { input: req.input, output, from, to, options };
+            // True cancellation: the timeout (or the caller) aborts an internal
+            // controller that converters actually observe, so work stops instead of
+            // being abandoned behind an already-returned promise.
+            const controller = new AbortController();
+            const onCallerAbort = () => controller.abort();
+            run.signal?.addEventListener('abort', onCallerAbort, { once: true });
             const ctx = {
                 logger: run.logger,
-                signal: run.signal,
+                signal: AbortSignal.any([controller.signal, ...(run.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;
+            let timer;
+            try {
+                const timeoutPromise = new Promise((resolve) => {
+                    timer = setTimeout(() => {
+                        controller.abort();
+                        resolve({
+                            ok: false,
+                            input: req.input,
+                            from,
+                            to,
+                            error: convertError('timeout', `Conversion exceeded ${Math.round(ctx.timeoutMs / 1000)}s and was cancelled.`),
+                        });
+                    }, ctx.timeoutMs);
+                });
+                const result = await Promise.race([converter.convert(request, ctx), timeoutPromise]);
+                if (result.ok)
+                    result.warnings.unshift(...warnings);
+                return result;
+            }
+            finally {
+                clearTimeout(timer);
+                run.signal?.removeEventListener('abort', onCallerAbort);
+            }
         }
         catch (err) {
             if (err instanceof DetectError) {
@@ -183,6 +207,16 @@ export class ConversionRouter {
         }
     }
     async inspect(input) {
+        const inputStat = await fs.stat(input).catch(() => null);
+        if (inputStat?.isDirectory()) {
+            throw new DetectError(convertError('invalid_input', `Input is a directory, not a file: ${input}`));
+        }
+        const maxInputBytes = this.defaults.maxInputBytes ?? 2 * 1024 ** 3;
+        if (inputStat && inputStat.size > maxInputBytes) {
+            throw new DetectError(convertError('invalid_input', `Input is ${Math.round(inputStat.size / 1048576).toLocaleString('en-US')} MB, above the ${Math.round(maxInputBytes / 1048576).toLocaleString('en-US')} MB limit for inspection.`, {
+                hint: "Raise 'maxInputMb' in the plugin config.",
+            }));
+        }
         const { detection } = await detectFile(input);
         const bytes = (await fs.stat(input)).size;
         let media;
@@ -199,51 +233,6 @@ export class ConversionRouter {
 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) {
@@ -264,25 +253,4 @@ async function exists(path) {
         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/utils/path-guard.d.ts

@@ -0,0 +1,13 @@
+/**
+ * realpath the deepest EXISTING ancestor of a path and rejoin the remainder:
+ * symlinks anywhere in the existing part are resolved, which is what output
+ * confinement and same-file checks need (a symlink inside a root can point
+ * outside, and two different-looking paths can be the same file).
+ */
+export declare function realPathBestEffort(p: string): Promise<string>;
+/** Same file on disk, comparing real paths (symlink/case/separator aware). */
+export declare function isSameFile(a: string, b: string): Promise<boolean>;
+/** True when `candidate` is `root` itself or lives inside it (real paths). */
+export declare function isInsideRoot(candidate: string, root: string): Promise<boolean>;
+/** True when the candidate is inside at least one of the roots. */
+export declare function isInsideAnyRoot(candidate: string, roots: string[] | undefined): Promise<boolean>;

package/lib/core/utils/path-guard.js

@@ -0,0 +1,53 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+/**
+ * realpath the deepest EXISTING ancestor of a path and rejoin the remainder:
+ * symlinks anywhere in the existing part are resolved, which is what output
+ * confinement and same-file checks need (a symlink inside a root can point
+ * outside, and two different-looking paths can be the same file).
+ */
+export 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;
+    }
+}
+/** Same file on disk, comparing real paths (symlink/case/separator aware). */
+export 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();
+}
+function normalizeForCompare(p) {
+    return process.platform === 'win32' ? p.replace(/\\/g, '/').toLowerCase() : p;
+}
+/** True when `candidate` is `root` itself or lives inside it (real paths). */
+export async function isInsideRoot(candidate, root) {
+    const realCandidate = normalizeForCompare(await realPathBestEffort(candidate));
+    const realRoot = normalizeForCompare(await realPathBestEffort(path.resolve(root)));
+    return realCandidate === realRoot || realCandidate.startsWith(realRoot.endsWith('/') ? realRoot : realRoot + '/');
+}
+/** True when the candidate is inside at least one of the roots. */
+export async function isInsideAnyRoot(candidate, roots) {
+    if (!roots || roots.length === 0)
+        return true;
+    for (const root of roots) {
+        if (await isInsideRoot(candidate, root))
+            return true;
+    }
+    return false;
+}

package/lib/core/utils/write-file.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Write `data` to `target` atomically: the bytes land in a sibling temp file
+ * first and are renamed into place only when complete, so an interrupted run
+ * never leaves a half-written output behind.
+ */
+export declare function writeFileAtomic(target: string, data: Buffer | string): Promise<void>;

package/lib/core/utils/write-file.js

@@ -0,0 +1,25 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+/**
+ * Write `data` to `target` atomically: the bytes land in a sibling temp file
+ * first and are renamed into place only when complete, so an interrupted run
+ * never leaves a half-written output behind.
+ */
+export async function writeFileAtomic(target, data) {
+    const tmp = path.join(path.dirname(target), `.${path.basename(target)}.${Date.now()}-${Math.random().toString(36).slice(2)}.tmp`);
+    try {
+        await fs.writeFile(tmp, data);
+        try {
+            await fs.rename(tmp, target);
+        }
+        catch {
+            // cross-device or platform quirk: fall back to a full copy
+            await fs.copyFile(tmp, target);
+            await fs.rm(tmp, { force: true });
+        }
+    }
+    catch (err) {
+        await fs.rm(tmp, { force: true }).catch(() => undefined);
+        throw err;
+    }
+}

package/lib/index.d.ts

@@ -1,6 +1,7 @@
 import type { Context } from '@deepseek-ai/cordis';
 import { type Config as ConvertConfig } from './config.js';
 export { Config } from './config.js';
+export * from './core/index.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

@@ -7,6 +7,9 @@ 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';
+// Library consumers (CLI, MCP wrapper, tests) can import the whole core
+// surface from the package root; the DSH loader only reads name/inject/apply.
+export * from './core/index.js';
 export const name = 'dsh-file-convert';
 export const inject = ['tools'];
 const CONSOLE_LOGGER = {

package/lib/tools/install-media.js

@@ -1,6 +1,6 @@
 import { defineTool } from '@deepseek-ai/dsh-tools';
 import { FFMPEG, FFPROBE, resolveBinary } from '../core/index.js';
-import { downloadBinary } from '../core/binaries/download.js';
+import { downloadBinary, readCacheManifest } from '../core/binaries/download.js';
 import { formatBytes } from '../format.js';
 /**
  * One explicit, user-approved path to media support: downloads pinned static
@@ -31,10 +31,14 @@ export function createInstallMediaTool(config, logger) {
             if (config.ffprobePath)
                 overrides.ffprobePath = config.ffprobePath;
             const lines = [];
+            const manifest = await readCacheManifest();
             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}`);
+                    if (!manifest[dep.name]) {
+                        lines.push(`~ ${dep.name}: the cached copy predates the manifest - run with force: true once to upgrade to a sha256-verified build`);
+                    }
                     continue;
                 }
                 logger.info(`downloading ${dep.name} into the plugin cache...`);

package/lib/tools/optimize-file.js

@@ -3,6 +3,7 @@ import path from 'node:path';
 import { defineTool } from '@deepseek-ai/dsh-tools';
 import { DetectError, optimizeFile, resolveBinary } from '../core/index.js';
 import { canonicalExtension } from '../core/index.js';
+import { isInsideAnyRoot } from '../core/index.js';
 import { formatBytes, formatDuration, formatFailure } from '../format.js';
 export function createOptimizeFileTool(router, config, logger) {
     return defineTool({
@@ -25,6 +26,13 @@ export function createOptimizeFileTool(router, config, logger) {
         isConcurrencySafe: () => true,
         async execute(args, exec) {
             const targetBytes = Math.max(1, Math.round(args.target_size_mb * 1024 * 1024));
+            const inputStat = await fs.stat(args.input).catch(() => null);
+            if (!inputStat)
+                throw new Error(`Input file not found: ${args.input}`);
+            const maxBytes = config.maxInputMb * 1024 * 1024;
+            if (inputStat.size > maxBytes) {
+                throw new Error(`Input is ${Math.round(inputStat.size / 1048576).toLocaleString('en-US')} MB, above the ${config.maxInputMb} MB limit. Raise 'maxInputMb' in the plugin config if this file is intentional.`);
+            }
             let detection;
             try {
                 detection = (await router.detect(args.input)).detection;
@@ -42,7 +50,7 @@ export function createOptimizeFileTool(router, config, logger) {
             if (path.resolve(output) === path.resolve(args.input)) {
                 throw new Error('Output path equals the input path; optimizing would destroy the source. Use the default -min output name or pick another path.');
             }
-            if (args.output !== undefined && config.outputRoots.length > 0 && !isInsideRoots(args.output, config.outputRoots)) {
+            if (args.output !== undefined && config.outputRoots.length > 0 && !(await isInsideAnyRoot(args.output, config.outputRoots))) {
                 throw new Error(`Output path is outside every configured outputRoot (${config.outputRoots.join(', ')}).`);
             }
             if (args.overwrite !== true && (await exists(output))) {
@@ -71,15 +79,6 @@ export function createOptimizeFileTool(router, config, logger) {
         },
     });
 }
-function isInsideRoots(output, roots) {
-    const resolved = path.resolve(output);
-    const candidate = process.platform === 'win32' ? resolved.replace(/\\/g, '/').toLowerCase() : resolved;
-    return roots.some((root) => {
-        const rr = path.resolve(root);
-        const prefix = process.platform === 'win32' ? rr.replace(/\\/g, '/').toLowerCase() : rr;
-        return candidate === prefix || candidate.startsWith(prefix.endsWith('/') ? prefix : prefix + '/');
-    });
-}
 async function exists(p) {
     try {
         await fs.access(p);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-file-convert",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Local-first file conversion for DeepSeek Harness - images, PDF, data, audio/video and office documents. No API keys, no uploads, no token cost.",
   "license": "MIT",
   "type": "module",