@mcptoolshop/toolshopstudio 1.1.0-toolshop

package/.dockerignore

@@ -0,0 +1,13 @@
+node_modules
+dist
+*.tsbuildinfo
+.git
+.env
+.env.*
+*.log
+src/**/*.test.ts
+src/__snapshots__
+smoke.mjs
+
+# Keep assets/ in Docker image (logo, etc.)
+!assets/

package/.github/workflows/ci.yml

@@ -0,0 +1,53 @@
+name: CI
+
+on:
+  push:
+    paths:
+      - "package.json"
+      - "tsconfig.json"
+      - "src/**"
+      - "smoke.mjs"
+      - ".github/workflows/**"
+  pull_request:
+    paths:
+      - "package.json"
+      - "tsconfig.json"
+      - "src/**"
+      - "smoke.mjs"
+      - ".github/workflows/**"
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    name: Typecheck + Test + Smoke
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        node-version: [22]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: "npm"
+
+      - run: npm ci
+
+      - name: Typecheck
+        run: npm run typecheck
+
+      - name: Unit tests (FFmpeg + Pandoc)
+        run: npm test
+
+      - name: Build
+        run: npm run build
+
+      - name: Smoke test (both tools)
+        run: npm run smoke

package/CHANGELOG.md

@@ -0,0 +1,44 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [1.1.0-toolshop] - 2026-02-19
+
+### Added
+- **Pandoc MCP**: full document conversion tool (5 presets: blog-post, academic-pdf, ebook, slides, newsletter)
+- Pandoc two-tier encoding: premium newsletter with automatic fallback to blog-post
+- Pandoc schema-first design: Zod schemas for ConvertDocument, PandocDocumentAsset, metadata
+- Pandoc buildPandocArgs pure function (deterministic, zero raw flags)
+- Pandoc progress parser reusing FFmpeg line-buffer infrastructure
+- Pandoc pre/post-flight assertions (input validation, output extension/size checks)
+- Pandoc context DI pattern (ConvertDocumentContext) matching FFmpeg's TranscodeContext
+- PandocDocumentCRUD with lazy hydration + optional JSON persistence
+- Output polish helpers (auto-extension, typed metadata, configurable expiry)
+- Unified Docker image with both ffmpeg and pandoc binaries + non-root user
+- GitHub Actions CI (paths-gated, single workflow, typecheck + test + build + smoke)
+- Dual-tool smoke test (FFmpeg + Pandoc end-to-end)
+- 42 unit/integration tests (13 FFmpeg + 29 Pandoc)
+
+### Changed
+- README refreshed for dual-tool story with both preset tables
+- Docker image relabeled for v1.1.0-toolshop
+- Release script updated with npm publish step
+
+---
+
+## [1.0.0-yt-safe] - 2026-02-19
+
+### Added
+- Full YouTube 2026 preset layer (7 presets: guaranteed + premium with fallback)
+- Two-tier encoding: premium H.265 with automatic fallback to guaranteed H.264
+- Closed-GOP locks on all presets (scenecut=0, keyint=60)
+- Dual thumbnail generation (16:9 landscape + 4:5 portrait) with style controls
+- Robust line-buffered ffmpeg progress parser with percent tracking
+- AbortController cancellation propagated to all pipeline stages
+- Pre-flight checks: interlace detection, output size estimation
+- Post-flight assertions: container, codec, profile, pix_fmt, audio spec validation
+- Zod schemas for all inputs/outputs (type-safe end-to-end)
+- In-memory CRUD with optional JSON file persistence
+- Context DI pattern for full testability (13 unit tests + smoke)
+- Multi-stage Docker image with OCI labels
+- Logo integrated

package/Dockerfile

@@ -0,0 +1,48 @@
+# ── Build stage ────────────────────────────────────────────────────
+FROM node:22-slim AS builder
+
+WORKDIR /app
+
+COPY package.json package-lock.json tsconfig.json ./
+RUN npm ci --ignore-scripts
+
+COPY src/ src/
+RUN npm run build
+
+# ── Production stage ───────────────────────────────────────────────
+FROM node:22-slim
+
+# Install both runtime binaries
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends \
+      ffmpeg \
+      pandoc \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+
+COPY package.json package-lock.json ./
+RUN npm ci --omit=dev --ignore-scripts
+
+COPY --from=builder /app/dist/ dist/
+COPY assets/ assets/
+
+# Non-root user for sandbox isolation
+RUN useradd -m -u 1001 appuser && \
+    mkdir -p /sandbox /tmp/toolshop && \
+    chown -R appuser:appuser /app /sandbox /tmp/toolshop
+
+USER appuser
+
+ENV NODE_ENV=production
+
+VOLUME ["/sandbox", "/tmp/toolshop"]
+
+LABEL org.opencontainers.image.title="ToolShopStudio" \
+      org.opencontainers.image.description="FFmpeg YouTube MCP + Pandoc MCP — dual-tool kit for ordinary creators" \
+      org.opencontainers.image.version="1.1.0-toolshop" \
+      org.opencontainers.image.logo="assets/logo.png" \
+      org.opencontainers.image.source="https://github.com/mcp-tool-shop-org/ToolShopStudio" \
+      org.opencontainers.image.licenses="MIT"
+
+ENTRYPOINT ["node", "dist/index.js"]

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mcp-tool-shop
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,110 @@
+<p align="center">
+  <img src="assets/logo.png" width="400" alt="ToolShopStudio">
+</p>
+
+<h1 align="center">ToolShopStudio</h1>
+
+<p align="center">
+  Production-grade MCP tools for ordinary creators
+</p>
+
+<p align="center">
+  <a href="https://github.com/mcp-tool-shop-org/ToolShopStudio/actions"><img src="https://github.com/mcp-tool-shop-org/ToolShopStudio/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://www.npmjs.com/package/@mcptoolshop/toolshopstudio"><img src="https://img.shields.io/npm/v/@mcptoolshop/toolshopstudio" alt="npm version"></a>
+  <img src="https://img.shields.io/badge/tools-FFmpeg%20%2B%20Pandoc-orange" alt="Tools">
+  <img src="https://img.shields.io/badge/tests-42%20passing-brightgreen" alt="Tests">
+  <img src="https://img.shields.io/badge/license-MIT-blue" alt="License">
+</p>
+
+---
+
+## Shipped Today
+
+| Tool | What It Does |
+|------|--------------|
+| **FFmpeg YouTube MCP** | YouTube-safe presets (guaranteed + premium with fallback), closed-GOP locks, dual thumbnails |
+| **Pandoc MCP** | Zero-flag document conversion: blog, academic PDF, ebook, slides, newsletter |
+
+Both tools share the same frozen surface: **schema-first, sandboxed, observable, context DI, zero raw args**.
+
+## Quick Start
+
+```bash
+npm install @mcptoolshop/toolshopstudio
+```
+
+```typescript
+import {
+  transcodeForYouTube,
+  createInMemoryCRUD,
+  pandoc,
+} from "@mcptoolshop/toolshopstudio";
+
+// ── FFmpeg: YouTube-safe transcode ──────────────────────────────
+const ffmpegCrud = createInMemoryCRUD();
+const video = await transcodeForYouTube(
+  { inputPath: "input.mp4", outputPath: "output.mp4", preset: "yt-1080p-h264" },
+  { signal, userId, notify, createAsset: (a) => ffmpegCrud.create(a), runFfmpeg, runProbe },
+);
+
+// ── Pandoc: document conversion ─────────────────────────────────
+const pandocCrud = pandoc.createPandocCRUD();
+const doc = await pandoc.convertDocument(
+  { inputPath: "thesis.md", outputPath: "thesis.pdf", preset: "academic-pdf" },
+  { signal, userId, notify, createAsset: (a) => pandocCrud.create(a), runPandoc, checkInput, assertOutput, statFile },
+);
+```
+
+## FFmpeg Presets
+
+| Preset | Codec | Resolution | CRF | Tier |
+|--------|-------|-----------|-----|------|
+| `yt-1080p-h264` | libx264 | 1920x1080 | 18 | Guaranteed |
+| `yt-1080p-h265` | libx265 | 1920x1080 | 20 | Premium |
+| `yt-4k-h264` | libx264 | 3840x2160 | 18 | Guaranteed |
+| `yt-4k-h265` | libx265 | 3840x2160 | 20 | Premium |
+| `yt-4k-hdr-h265` | libx265 | 3840x2160 | 18 | Premium (HDR) |
+| `yt-shorts-h264` | libx264 | 1080x1920 | 18 | Guaranteed |
+| `yt-shorts-h265` | libx265 | 1080x1920 | 20 | Premium |
+
+## Pandoc Presets
+
+| Preset | From | To | Output | Tier |
+|--------|------|----|--------|------|
+| `blog-post` | Markdown | HTML5 | `.html` | Guaranteed |
+| `academic-pdf` | Markdown | PDF (XeLaTeX) | `.pdf` | Guaranteed |
+| `ebook` | Markdown | EPUB | `.epub` | Guaranteed |
+| `slides` | Markdown | Reveal.js | `.html` | Guaranteed |
+| `newsletter` | Markdown | HTML5 | `.html` | Premium (falls back to blog-post) |
+
+## Architecture
+
+- **Schema-first**: Zod schemas for every input/output, fully type-safe
+- **Context DI**: All side effects injected via context objects, 100% mockable
+- **Sandbox isolation**: Path traversal prevention on every file operation
+- **Observable**: Typed notifications (progress, warnings, ready) at every stage
+- **Cancellation**: AbortController propagated to every pipeline checkpoint
+- **Fallback**: Premium presets auto-degrade to guaranteed on failure/assertion mismatch
+
+## Docker
+
+```bash
+docker build -t toolshopstudio .
+docker run -v ./sandbox:/sandbox toolshopstudio
+```
+
+Both `ffmpeg` and `pandoc` binaries are pre-installed in the image.
+
+## Development
+
+```bash
+npm install          # dependencies
+npm run typecheck    # tsc --noEmit
+npm test             # vitest (42 tests)
+npm run build        # compile to dist/
+npm run smoke        # end-to-end smoke (both tools)
+```
+
+## License
+
+MIT

package/dist/build-flags.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Pure, deterministic ffmpeg flag builder.
+ * YouTube 2026 invariant compliant.
+ *
+ * Takes a transcode request + probe result, returns the full ffmpeg
+ * argv (minus the `ffmpeg` binary itself). No side effects.
+ */
+import type { TranscodeForYouTube, ProbeResult } from "./schemas.js";
+/**
+ * Build the complete ffmpeg flag array for a YouTube-safe transcode.
+ *
+ * Order: input → base flags → video filter → codec/pixFmt/profile/crf/maxrate →
+ *        HDR tags → customBitrate override → closed-GOP params → -y output
+ */
+export declare function buildFlags(req: TranscodeForYouTube, probe: ProbeResult): string[];

package/dist/build-flags.js

@@ -0,0 +1,95 @@
+/**
+ * Pure, deterministic ffmpeg flag builder.
+ * YouTube 2026 invariant compliant.
+ *
+ * Takes a transcode request + probe result, returns the full ffmpeg
+ * argv (minus the `ffmpeg` binary itself). No side effects.
+ */
+import { PRESET_SPECS, buildBaseFlags } from "./preset-spec.js";
+/**
+ * Build the complete ffmpeg flag array for a YouTube-safe transcode.
+ *
+ * Order: input → base flags → video filter → codec/pixFmt/profile/crf/maxrate →
+ *        HDR tags → customBitrate override → closed-GOP params → -y output
+ */
+export function buildFlags(req, probe) {
+    const spec = PRESET_SPECS[req.preset];
+    const flags = [];
+    // ── Input ───────────────────────────────────────────────────────
+    flags.push("-i", req.inputPath);
+    // ── Base invariants ─────────────────────────────────────────────
+    flags.push(...buildBaseFlags());
+    // ── Video filter (orientation-aware) ────────────────────────────
+    flags.push("-vf", resolveVf(spec.vf, req.orientationHint, probe));
+    // ── Codec, pixel format, profile, CRF, rate control ─────────────
+    flags.push("-c:v", spec.codec);
+    flags.push("-pix_fmt", spec.pixFmt);
+    flags.push("-profile:v", spec.profile);
+    flags.push("-crf", String(spec.crf));
+    flags.push("-maxrate", spec.maxrate);
+    flags.push("-bufsize", spec.bufsize);
+    // ── HDR tags (only for HDR presets) ─────────────────────────────
+    if (spec.hdrTags) {
+        for (const [key, value] of Object.entries(spec.hdrTags)) {
+            flags.push(`-${key}`, value);
+        }
+    }
+    // ── Custom bitrate override ─────────────────────────────────────
+    if (req.customBitrate?.videoMbps) {
+        flags.push("-b:v", `${req.customBitrate.videoMbps}M`);
+    }
+    if (req.customBitrate?.audioBitrate) {
+        flags.push("-b:a", req.customBitrate.audioBitrate);
+    }
+    // ── Closed-GOP encoder params ───────────────────────────────────
+    if (spec.codec === "libx264" && spec.x264Params) {
+        flags.push("-x264-params", spec.x264Params);
+    }
+    if (spec.codec === "libx265" && spec.x265Params) {
+        flags.push("-x265-params", spec.x265Params);
+    }
+    // ── Progress pipe (stderr key=value parsing) ────────────────────
+    flags.push("-progress", "pipe:2");
+    // ── Output (overwrite) ──────────────────────────────────────────
+    flags.push("-y", req.outputPath);
+    return flags;
+}
+// ── Helpers ─────────────────────────────────────────────────────────
+/**
+ * Resolve the video filter string. If an orientationHint is given
+ * and differs from the spec's default, swap width/height in the
+ * scale+pad chain. Otherwise use the spec's vf as-is.
+ */
+function resolveVf(specVf, orientationHint, _probe) {
+    if (!orientationHint)
+        return specVf;
+    // Parse the spec's scale dimensions from the vf string
+    const scaleMatch = specVf.match(/scale=(\d+):(\d+):force_original_aspect_ratio=decrease,pad=(\d+):(\d+)/);
+    if (!scaleMatch)
+        return specVf;
+    const [, sw, sh, pw, ph] = scaleMatch;
+    const specW = Number(sw);
+    const specH = Number(sh);
+    const specIsLandscape = specW > specH;
+    const wantLandscape = orientationHint === "landscape";
+    const wantPortrait = orientationHint === "portrait";
+    const wantSquare = orientationHint === "square";
+    // If hint matches spec orientation, no change needed
+    if ((wantLandscape && specIsLandscape) || (wantPortrait && !specIsLandscape)) {
+        return specVf;
+    }
+    // Swap dimensions for orientation mismatch
+    if ((wantPortrait && specIsLandscape) || (wantLandscape && !specIsLandscape)) {
+        return specVf
+            .replace(`scale=${sw}:${sh}`, `scale=${sh}:${sw}`)
+            .replace(`pad=${pw}:${ph}`, `pad=${ph}:${pw}`);
+    }
+    // Square: use min dimension for both
+    if (wantSquare) {
+        const dim = Math.min(specW, specH);
+        return specVf
+            .replace(`scale=${sw}:${sh}`, `scale=${dim}:${dim}`)
+            .replace(`pad=${pw}:${ph}`, `pad=${dim}:${dim}`);
+    }
+    return specVf;
+}

package/dist/crud.d.ts

@@ -0,0 +1,8 @@
+import type { YouTubeMediaAssetCRUD } from "./types.js";
+/**
+ * Create an in-memory CRUD store. Optionally persists to a JSON file
+ * on every write for dev/debug use.
+ *
+ * @param persistPath - optional path to a JSON file for persistence
+ */
+export declare function createInMemoryCRUD(persistPath?: string): YouTubeMediaAssetCRUD;

package/dist/crud.js

@@ -0,0 +1,76 @@
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import path from "node:path";
+// ── In-memory CRUD ────────────────────────────────────────────────
+/**
+ * Create an in-memory CRUD store. Optionally persists to a JSON file
+ * on every write for dev/debug use.
+ *
+ * @param persistPath - optional path to a JSON file for persistence
+ */
+export function createInMemoryCRUD(persistPath) {
+    const store = new Map();
+    async function persist() {
+        if (!persistPath)
+            return;
+        await mkdir(path.dirname(persistPath), { recursive: true });
+        const data = JSON.stringify(Array.from(store.values()), null, 2);
+        await writeFile(persistPath, data, "utf8");
+    }
+    async function hydrate() {
+        if (!persistPath)
+            return;
+        try {
+            const data = await readFile(persistPath, "utf8");
+            const items = JSON.parse(data);
+            for (const item of items) {
+                store.set(item.id, item);
+            }
+        }
+        catch {
+            // File doesn't exist yet — start fresh
+        }
+    }
+    // Hydrate on first access (lazy)
+    let hydrated = false;
+    async function ensureHydrated() {
+        if (!hydrated) {
+            await hydrate();
+            hydrated = true;
+        }
+    }
+    return {
+        async create(asset) {
+            await ensureHydrated();
+            store.set(asset.id, asset);
+            await persist();
+            return asset;
+        },
+        async read(id) {
+            await ensureHydrated();
+            return store.get(id) ?? null;
+        },
+        async list(filter) {
+            await ensureHydrated();
+            const all = Array.from(store.values());
+            // userId filter is a no-op for now (assets don't store userId)
+            return filter?.userId ? all : all;
+        },
+        async update(id, patch) {
+            await ensureHydrated();
+            const existing = store.get(id);
+            if (!existing)
+                throw new Error(`Asset ${id} not found.`);
+            const updated = { ...existing, ...patch, id }; // id is immutable
+            store.set(id, updated);
+            await persist();
+            return updated;
+        },
+        async delete(id) {
+            await ensureHydrated();
+            if (!store.delete(id)) {
+                throw new Error(`Asset ${id} not found.`);
+            }
+            await persist();
+        },
+    };
+}

package/dist/engine.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/engine.test.js

@@ -0,0 +1,150 @@
+import { describe, it, expect } from "vitest";
+import { buildFlags } from "./build-flags.js";
+import { parseProgressLine, calculatePercent, } from "./progress-parser.js";
+// ── Test fixtures ─────────────────────────────────────────────────
+const MINIMAL_PROBE = {
+    streams: [
+        {
+            codec_name: "h264",
+            codec_type: "video",
+            width: 1920,
+            height: 1080,
+            pix_fmt: "yuv420p",
+            field_order: "progressive",
+            r_frame_rate: "30/1",
+        },
+        {
+            codec_name: "aac",
+            codec_type: "audio",
+            channels: 2,
+            sample_rate: "48000",
+        },
+    ],
+    format: {
+        filename: "input.mp4",
+        format_name: "mov,mp4,m4a,3gp,3g2,mj2",
+        duration: "120.0",
+        bit_rate: "8000000",
+    },
+};
+// ── buildFlags golden snapshots ───────────────────────────────────
+describe("buildFlags", () => {
+    it("sdr_1080p: produces correct flags for yt-1080p-h264", () => {
+        const req = {
+            inputPath: "/sandbox/user1/input.mp4",
+            outputPath: "/sandbox/user1/output.mp4",
+            preset: "yt-1080p-h264",
+            allowFallback: true,
+            timeoutSeconds: 3600,
+        };
+        const flags = buildFlags(req, MINIMAL_PROBE);
+        expect(flags).toMatchSnapshot();
+    });
+    it("shorts_sdr_1080x1920: produces correct flags for yt-shorts-h264", () => {
+        const req = {
+            inputPath: "/sandbox/user1/short.mp4",
+            outputPath: "/sandbox/user1/short_out.mp4",
+            preset: "yt-shorts-h264",
+            allowFallback: true,
+            timeoutSeconds: 3600,
+        };
+        const flags = buildFlags(req, MINIMAL_PROBE);
+        expect(flags).toMatchSnapshot();
+    });
+    it("hdr_pq_4k: produces correct flags for yt-4k-hdr-h265", () => {
+        const req = {
+            inputPath: "/sandbox/user1/hdr_input.mp4",
+            outputPath: "/sandbox/user1/hdr_output.mp4",
+            preset: "yt-4k-hdr-h265",
+            allowFallback: true,
+            timeoutSeconds: 3600,
+        };
+        const flags = buildFlags(req, MINIMAL_PROBE);
+        expect(flags).toMatchSnapshot();
+        // HDR tags must be present
+        expect(flags).toContain("-color_primaries");
+        expect(flags).toContain("bt2020");
+        expect(flags).toContain("-color_trc");
+        expect(flags).toContain("smpte2084");
+        expect(flags).toContain("-colorspace");
+        expect(flags).toContain("bt2020nc");
+    });
+    it("closed-gop params are present for all presets", () => {
+        const presets = [
+            "yt-1080p-h264",
+            "yt-1080p-h265",
+            "yt-4k-h264",
+            "yt-4k-h265",
+            "yt-4k-hdr-h265",
+            "yt-shorts-h264",
+            "yt-shorts-h265",
+        ];
+        for (const preset of presets) {
+            const req = {
+                inputPath: "/in.mp4",
+                outputPath: "/out.mp4",
+                preset,
+                allowFallback: true,
+                timeoutSeconds: 3600,
+            };
+            const flags = buildFlags(req, MINIMAL_PROBE);
+            if (preset.includes("h264")) {
+                expect(flags).toContain("-x264-params");
+                const idx = flags.indexOf("-x264-params");
+                expect(flags[idx + 1]).toBe("keyint=60:min-keyint=60:scenecut=0");
+            }
+            else {
+                expect(flags).toContain("-x265-params");
+                const idx = flags.indexOf("-x265-params");
+                expect(flags[idx + 1]).toBe("open-gop=0:scenecut=0");
+            }
+        }
+    });
+});
+// ── Progress parser ───────────────────────────────────────────────
+describe("progress parser", () => {
+    it("handles split chunks correctly", () => {
+        // Simulate ffmpeg progress output that arrives in split chunks
+        const collected = [];
+        // Chunk 1: complete line + partial line
+        const chunk1 = "frame=100\nfps=30.0\nout_time_us=333";
+        // Chunk 2: rest of partial line + new complete line
+        const chunk2 = "3000\nprogress=continue\n";
+        // Process chunk1
+        let buffer = "";
+        buffer += chunk1;
+        const lines1 = buffer.split("\n");
+        buffer = lines1.pop() ?? "";
+        for (const line of lines1) {
+            const kv = parseProgressLine(line);
+            if (kv)
+                collected.push(kv);
+        }
+        // Process chunk2
+        buffer += chunk2;
+        const lines2 = buffer.split("\n");
+        buffer = lines2.pop() ?? "";
+        for (const line of lines2) {
+            const kv = parseProgressLine(line);
+            if (kv)
+                collected.push(kv);
+        }
+        expect(collected).toEqual([
+            { key: "frame", value: "100" },
+            { key: "fps", value: "30.0" },
+            { key: "out_time_us", value: "3333000" },
+            { key: "progress", value: "continue" },
+        ]);
+    });
+    it("calculatePercent clamps to 0-100", () => {
+        expect(calculatePercent("0", 120)).toBe(0);
+        expect(calculatePercent("60000000", 120)).toBe(50);
+        expect(calculatePercent("120000000", 120)).toBe(100);
+        // Over 100% — clamped
+        expect(calculatePercent("150000000", 120)).toBe(100);
+        // Negative — clamped
+        expect(calculatePercent("-1000", 120)).toBe(0);
+        // Zero duration
+        expect(calculatePercent("50000000", 0)).toBe(0);
+    });
+});

package/dist/exec.d.ts

@@ -0,0 +1,14 @@
+import { type ProbeResult } from "./schemas.js";
+/**
+ * Run ffmpeg with -nostdin, AbortSignal cancellation, and progress parsing.
+ *
+ * @param flags - full argv (everything after `ffmpeg`)
+ * @param signal - AbortSignal for cancellation
+ * @param onProgress - called with percent (0–100), fires at each out_time_us update and on 'end'
+ * @param durationSec - total input duration for percent calculation
+ */
+export declare function runFfmpeg(flags: string[], signal: AbortSignal, onProgress: (percent: number) => void, durationSec: number): Promise<void>;
+/**
+ * Run ffprobe and return parsed ProbeResult.
+ */
+export declare function runProbe(filePath: string): Promise<ProbeResult>;