@openvidstudio/mcp-server 0.1.0

package/dist/tools/validateBeats.js

@@ -0,0 +1,164 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateBeatsLogic = validateBeatsLogic;
+exports.registerValidateBeats = registerValidateBeats;
+const zod_1 = require("zod");
+const capture_1 = require("../capture");
+const mcp_1 = require("./mcp");
+const EM_DASH = "—";
+const MIN_PACE = 2.3;
+const MAX_PACE = 2.9;
+const CAPTURE_METHODS = ["screenshot", "recording", "dom-demo", "higgsfield"];
+function wordCount(text) {
+    const trimmed = text.trim();
+    return trimmed.length === 0 ? 0 : trimmed.split(/\s+/).length;
+}
+/**
+ * Mechanically enforces packages/docs/PLANNING.md §4 (captureMethod field spec) and
+ * packages/docs/SCRIPT.md (VO pacing, no em dashes). Takes the drafted beats.json
+ * content directly (not yet written to disk, not assumed to already be valid), and
+ * returns every failure found rather than stopping at the first -- this is the tool's
+ * normal "no" answer, never a thrown exception.
+ */
+function validateBeatsLogic(beatsJson) {
+    const errors = [];
+    if (typeof beatsJson !== "object" || beatsJson === null) {
+        return { valid: false, errors: ["beatsJson must be an object"] };
+    }
+    const root = beatsJson;
+    const fps = typeof root.fps === "number" && root.fps > 0 ? root.fps : 30;
+    if (!Array.isArray(root.beats)) {
+        return { valid: false, errors: ["beatsJson.beats must be an array"] };
+    }
+    const beats = root.beats;
+    if (beats.length === 0) {
+        errors.push("beats array is empty");
+    }
+    const seenIds = new Set();
+    let expectedStart = 0;
+    beats.forEach((raw, i) => {
+        if (typeof raw !== "object" || raw === null) {
+            errors.push(`beat[${i}]: is not an object`);
+            return;
+        }
+        const beat = raw;
+        const label = typeof beat.id === "string" && beat.id.length > 0 ? `beat "${beat.id}"` : `beat[${i}]`;
+        if (typeof beat.id !== "string" || beat.id.length === 0) {
+            errors.push(`${label}: missing or invalid "id"`);
+        }
+        else if (seenIds.has(beat.id)) {
+            errors.push(`${label}: duplicate beat id`);
+        }
+        else {
+            seenIds.add(beat.id);
+        }
+        const start = beat.start;
+        const duration = beat.duration;
+        const hasStart = typeof start === "number";
+        const hasDuration = typeof duration === "number" && duration > 0;
+        if (!hasStart) {
+            errors.push(`${label}: missing or invalid "start"`);
+        }
+        else if (start !== expectedStart) {
+            errors.push(`${label}: "start" (${start}) must equal ${expectedStart} (contiguous timing: the first beat starts ` +
+                `at 0, every later beat starts at the previous beat's start + duration)`);
+        }
+        if (!hasDuration) {
+            errors.push(`${label}: missing or invalid "duration" (must be a positive number)`);
+        }
+        if (hasStart && hasDuration) {
+            expectedStart = start + duration;
+        }
+        else if (hasDuration) {
+            expectedStart += duration;
+        }
+        const vo = beat.vo;
+        if (typeof vo !== "string" || vo.length === 0) {
+            errors.push(`${label}: missing or invalid "vo"`);
+        }
+        else {
+            if (vo.includes(EM_DASH)) {
+                errors.push(`${label}: "vo" contains an em dash, rewrite with commas/periods`);
+            }
+            if (hasDuration) {
+                const seconds = duration / fps;
+                if (seconds > 0) {
+                    const words = wordCount(vo);
+                    const pace = words / seconds;
+                    if (pace < MIN_PACE || pace > MAX_PACE) {
+                        errors.push(`${label}: VO pace ${pace.toFixed(2)} words/sec is outside the ${MIN_PACE}-${MAX_PACE} words/sec ` +
+                            `budget (${words} words over ${seconds.toFixed(2)}s, per SCRIPT.md)`);
+                    }
+                }
+            }
+        }
+        const visual = beat.visual;
+        if (typeof visual !== "object" || visual === null) {
+            errors.push(`${label}: missing or invalid "visual"`);
+            return;
+        }
+        const v = visual;
+        for (const [key, val] of Object.entries(v)) {
+            if (typeof val === "string" && val.includes(EM_DASH)) {
+                errors.push(`${label}: visual.${key} contains an em dash, rewrite with commas/periods`);
+            }
+        }
+        const captureMethod = v.captureMethod;
+        if (typeof captureMethod !== "string" || !CAPTURE_METHODS.includes(captureMethod)) {
+            errors.push(`${label}: visual.captureMethod must be one of ${CAPTURE_METHODS.map((m) => `"${m}"`).join(", ")}`);
+            return;
+        }
+        if (captureMethod === "screenshot" || captureMethod === "recording") {
+            if (typeof v.url !== "string" || v.url.length === 0) {
+                errors.push(`${label}: visual.url is required for captureMethod "${captureMethod}"`);
+            }
+            if (!Array.isArray(v.interactions)) {
+                errors.push(`${label}: visual.interactions (array, may be empty) is required for captureMethod "${captureMethod}"`);
+            }
+            else {
+                // Validate each interaction against the exact zod schema capture_screenshot /
+                // capture_screen_recording enforce at replay time (interactionSchema, from
+                // capture.ts), so a schema violation (e.g. a "navigate" or "type" step, which
+                // this pipeline does not support) surfaces here at draft time, not at capture
+                // time.
+                v.interactions.forEach((interaction, idx) => {
+                    const parsed = capture_1.interactionSchema.safeParse(interaction);
+                    if (!parsed.success) {
+                        const issues = parsed.error.issues.map((issue) => `${issue.path.join(".") || "(root)"}: ${issue.message}`);
+                        errors.push(`${label}: visual.interactions[${idx}] is invalid: ${issues.join("; ")}`);
+                    }
+                });
+            }
+        }
+        else if (captureMethod === "higgsfield") {
+            if (typeof v.higgsfieldPrompt !== "string" || v.higgsfieldPrompt.length === 0) {
+                errors.push(`${label}: visual.higgsfieldPrompt is required for captureMethod "higgsfield"`);
+            }
+        }
+        // dom-demo: no additional required fields.
+    });
+    return { valid: errors.length === 0, errors };
+}
+function registerValidateBeats(server) {
+    server.registerTool("validate_beats", {
+        title: "Validate a drafted beats.json",
+        description: "Mechanically checks a drafted beats.json (an object, not a file path -- it hasn't been written to " +
+            "disk yet) against PLANNING.md's captureMethod field spec and SCRIPT.md's pacing rules: contiguous " +
+            "frame timing (30fps unless the file states its own fps; the first beat starts at 0, every later " +
+            "beat starts at the previous beat's start + duration), no em dashes in vo/visual string fields, VO " +
+            "word-count vs the 2.3-2.9 words/sec budget checked in both directions (too many words for the " +
+            "duration and suspiciously few), every beat has a captureMethod, and method-specific required " +
+            "fields (url + interactions for screenshot/recording, higgsfieldPrompt for higgsfield, nothing extra " +
+            "for dom-demo). For screenshot/recording beats, every interactions[] entry is also validated against " +
+            "the exact schema capture_screenshot/capture_screen_recording enforce at replay time (click, fill, " +
+            "select, hover, scroll, wait), so a shape mismatch fails here at draft time instead of at capture " +
+            "time. Returns { valid, errors } with every failure found, never just the first -- this is " +
+            "the tool's normal answer for an invalid draft, not an exceptional case, so it never throws for a " +
+            "validation failure.",
+        inputSchema: {
+            beatsJson: zod_1.z
+                .unknown()
+                .describe("The drafted beats.json content (an object), not a file path."),
+        },
+    }, async ({ beatsJson }) => (0, mcp_1.runTool)("validate_beats", () => validateBeatsLogic(beatsJson)));
+}

package/dist/tools/validateScenes.d.ts

@@ -0,0 +1,31 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+/**
+ * The worst failure class in this pipeline is silent wrongness: a scene renders
+ * successfully and is simply wrong.
+ *
+ * The commonest instance is framing. Scenes lay content out on a 1920x1080 stage, but
+ * the camera only ever shows stage divided by scale, so at 1.4 that is 1371x771 and
+ * anything wider is cropped at the frame edge. Nothing errors. Building one real video
+ * this cropped three scenes, and it was only caught by rendering stills and looking.
+ *
+ * This reads the scene sources and reports the mismatches that are visible statically:
+ * camera scales against the content widths declared in the file, missing capture
+ * assets, and scenes that never move.
+ */
+export interface ValidateScenesInput {
+    projectRoot?: string;
+    videoName: string;
+}
+export interface SceneFinding {
+    beatId: string;
+    scene: string;
+    severity: "error" | "warning";
+    message: string;
+}
+export interface ValidateScenesResult {
+    ok: boolean;
+    scenesChecked: number;
+    findings: SceneFinding[];
+}
+export declare function runValidateScenes(input: ValidateScenesInput): ValidateScenesResult;
+export declare function registerValidateScenes(server: McpServer): void;

package/dist/tools/validateScenes.js

@@ -0,0 +1,191 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runValidateScenes = runValidateScenes;
+exports.registerValidateScenes = registerValidateScenes;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const zod_1 = require("zod");
+const util_1 = require("../util");
+const config_1 = require("../config");
+const mcp_1 = require("./mcp");
+const STAGE_W = 1920;
+const STAGE_H = 1080;
+/** Every numeric `scale:` in the camera array. */
+function cameraScales(src) {
+    return [...src.matchAll(/scale:\s*([\d.]+)/g)]
+        .map((m) => Number.parseFloat(m[1]))
+        .filter((n) => Number.isFinite(n));
+}
+/** Explicit pixel widths a scene declares, which is what gets cropped. */
+function declaredWidths(src) {
+    const out = [];
+    for (const m of src.matchAll(/\bwidth[=:]\s*\{?\s*(\d{3,4})\b/g))
+        out.push(Number(m[1]));
+    for (const m of src.matchAll(/\bFRAME_W\s*=\s*(\d{3,4})\b/g))
+        out.push(Number(m[1]));
+    for (const m of src.matchAll(/\bmaxWidth:\s*(\d{3,4})\b/g))
+        out.push(Number(m[1]));
+    return out;
+}
+function runValidateScenes(input) {
+    const videoName = (0, util_1.sanitizeSegment)(input.videoName, "videoName");
+    const projectRoot = (0, util_1.resolveProjectRoot)(input.projectRoot);
+    const config = (0, config_1.loadConfig)(projectRoot);
+    const videoDir = path.join(projectRoot, "src", "videos", videoName);
+    const scenesDir = path.join(videoDir, "scenes");
+    const beatsFile = path.join(videoDir, "beats.json");
+    if (!fs.existsSync(beatsFile)) {
+        throw new Error(`No beats.json at ${beatsFile}. Run write_beats_file first.`);
+    }
+    const doc = JSON.parse(fs.readFileSync(beatsFile, "utf8"));
+    const findings = [];
+    let checked = 0;
+    for (const beat of doc.beats) {
+        const component = (0, util_1.pascalCase)(beat.id);
+        const file = path.join(scenesDir, `${component}.tsx`);
+        if (!fs.existsSync(file)) {
+            findings.push({
+                beatId: beat.id,
+                scene: `${component}.tsx`,
+                severity: "error",
+                message: `No scene file. Run scaffold_scene for this beat.`,
+            });
+            continue;
+        }
+        checked++;
+        const src = fs.readFileSync(file, "utf8");
+        // Framing. The binding number is the scene's highest scale, not its first.
+        const scales = cameraScales(src);
+        const maxScale = scales.length ? Math.max(...scales) : 1;
+        const visibleW = Math.round(STAGE_W / maxScale);
+        const visibleH = Math.round(STAGE_H / maxScale);
+        for (const w of declaredWidths(src)) {
+            if (w > visibleW) {
+                findings.push({
+                    beatId: beat.id,
+                    scene: `${component}.tsx`,
+                    severity: "error",
+                    message: `Content declares ${w}px wide but the camera reaches scale ${maxScale}, which shows only ` +
+                        `${visibleW}x${visibleH} of the stage. It will be cropped at the frame edge and the render ` +
+                        `will not warn. Narrow the content or lower the camera scale.`,
+                });
+            }
+        }
+        // Motion. A frozen frame is a QC fail in STYLE.md.
+        if (scales.length >= 2 && new Set(scales).size === 1) {
+            const positions = new Set([...src.matchAll(/\bx:\s*(\d+),\s*y:\s*(\d+)/g)].map((m) => `${m[1]},${m[2]}`));
+            if (positions.size <= 1) {
+                findings.push({
+                    beatId: beat.id,
+                    scene: `${component}.tsx`,
+                    severity: "warning",
+                    message: `Camera never moves. STYLE.md fails a static frame; give it at least a subtle push.`,
+                });
+            }
+        }
+        if (scales.length < 2) {
+            findings.push({
+                beatId: beat.id,
+                scene: `${component}.tsx`,
+                severity: "warning",
+                message: `Fewer than two camera keyframes, so nothing moves.`,
+            });
+        }
+        // Capture assets the scene references but that are not on disk yet.
+        const method = beat.visual?.captureMethod;
+        if (method === "screenshot") {
+            const asset = path.join(projectRoot, "public", "images", `${beat.id}.png`);
+            if (!fs.existsSync(asset)) {
+                findings.push({
+                    beatId: beat.id,
+                    scene: `${component}.tsx`,
+                    severity: "error",
+                    message: `References public/images/${beat.id}.png, which does not exist. Run capture_screenshot.`,
+                });
+            }
+        }
+        if (method === "recording" || method === "higgsfield") {
+            const asset = path.join(projectRoot, "public", "video", `${beat.id}.mp4`);
+            if (!fs.existsSync(asset)) {
+                findings.push({
+                    beatId: beat.id,
+                    scene: `${component}.tsx`,
+                    severity: "error",
+                    message: `References public/video/${beat.id}.mp4, which does not exist.`,
+                });
+            }
+        }
+        if (/TODO/.test(src)) {
+            findings.push({
+                beatId: beat.id,
+                scene: `${component}.tsx`,
+                severity: "warning",
+                message: `Still contains a TODO.`,
+            });
+        }
+    }
+    // Narration, which stitch_composition skips silently when absent.
+    for (const beat of doc.beats) {
+        const vo = path.join(projectRoot, "public", "audio", "vo", `${beat.id}.mp3`);
+        if (!fs.existsSync(vo)) {
+            findings.push({
+                beatId: beat.id,
+                scene: "-",
+                severity: "warning",
+                message: `No narration at public/audio/vo/${beat.id}.mp3. stitch_composition skips this silently, so the ` +
+                    `beat renders with no voice and nothing reports it. Run generate_narration.`,
+            });
+        }
+    }
+    void config;
+    return { ok: !findings.some((f) => f.severity === "error"), scenesChecked: checked, findings };
+}
+function registerValidateScenes(server) {
+    server.registerTool("validate_scenes", {
+        title: "Check scenes for problems that render without erroring",
+        description: "Reads every scene for a video and reports what would otherwise only be caught by watching the " +
+            "output. Chiefly framing: content is laid out on a 1920x1080 stage but the camera shows stage " +
+            "divided by scale, so a panel wider than the visible box is cropped at the frame edge with no " +
+            "warning at all. Also flags scenes whose camera never moves (a static frame fails STYLE.md), " +
+            "capture assets a scene references that are not on disk, leftover TODOs, and beats with no " +
+            "narration file, since stitch_composition skips those silently and the beat renders mute. Run it " +
+            "after scaffolding and again before rendering.",
+        inputSchema: {
+            projectRoot: zod_1.z.string().optional(),
+            videoName: zod_1.z.string().min(1),
+        },
+    }, async (input) => (0, mcp_1.runTool)("validate_scenes", () => runValidateScenes(input)));
+}

package/dist/tools/writeBeatsFile.d.ts

@@ -0,0 +1,20 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type ValidateBeatsResult } from "./validateBeats";
+export interface WriteBeatsFileInput {
+    projectRoot?: string;
+    videoName: string;
+    beatsJson: unknown;
+}
+export type WriteBeatsFileResult = {
+    written: true;
+    path: string;
+} | ValidateBeatsResult;
+/**
+ * Runs validate_beats' own logic directly (no MCP round-trip) and refuses to write
+ * anything invalid. This is the mechanical half of PLANNING.md's "approval gate": it
+ * enforces schema validity, not the human-approval step itself (the calling agent
+ * must show the dev the full drafted beats.json and get explicit approval before ever
+ * calling this tool -- see the tool description below).
+ */
+export declare function runWriteBeatsFile(input: WriteBeatsFileInput): WriteBeatsFileResult;
+export declare function registerWriteBeatsFile(server: McpServer): void;

package/dist/tools/writeBeatsFile.js

@@ -0,0 +1,81 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runWriteBeatsFile = runWriteBeatsFile;
+exports.registerWriteBeatsFile = registerWriteBeatsFile;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const zod_1 = require("zod");
+const validateBeats_1 = require("./validateBeats");
+const util_1 = require("../util");
+const mcp_1 = require("./mcp");
+/**
+ * Runs validate_beats' own logic directly (no MCP round-trip) and refuses to write
+ * anything invalid. This is the mechanical half of PLANNING.md's "approval gate": it
+ * enforces schema validity, not the human-approval step itself (the calling agent
+ * must show the dev the full drafted beats.json and get explicit approval before ever
+ * calling this tool -- see the tool description below).
+ */
+function runWriteBeatsFile(input) {
+    const validation = (0, validateBeats_1.validateBeatsLogic)(input.beatsJson);
+    if (!validation.valid) {
+        return validation;
+    }
+    const videoName = (0, util_1.sanitizeSegment)(input.videoName, "videoName");
+    const projectRoot = (0, util_1.resolveProjectRoot)(input.projectRoot);
+    const videoDir = path.join(projectRoot, "src", "videos", videoName);
+    fs.mkdirSync(videoDir, { recursive: true });
+    const filePath = path.join(videoDir, "beats.json");
+    fs.writeFileSync(filePath, JSON.stringify(input.beatsJson, null, 2) + "\n", "utf8");
+    return { written: true, path: filePath };
+}
+function registerWriteBeatsFile(server) {
+    server.registerTool("write_beats_file", {
+        title: "Write a validated beats.json to disk",
+        description: "Runs validate_beats' own validation logic internally first (a direct function call, not an MCP " +
+            "round-trip) and refuses to write anything invalid, returning the same { valid: false, errors } " +
+            "shape instead. On success writes src/videos/<videoName>/beats.json (pretty-printed, 2-space indent) " +
+            "and returns { written: true, path }. IMPORTANT: this tool only enforces schema validity. It does " +
+            "NOT enforce PLANNING.md's mandatory human-approval gate -- the calling agent must show the dev the " +
+            "full drafted beats.json (not a summary) and get explicit approval before ever calling this tool, " +
+            "even for a small, obviously-fine-looking draft. Passing this tool's validation is necessary but " +
+            "not sufficient; it is not a substitute for that approval step.",
+        inputSchema: {
+            projectRoot: zod_1.z.string().optional(),
+            videoName: zod_1.z.string().min(1),
+            beatsJson: zod_1.z.unknown().describe("The drafted beats.json content (an object), not a file path."),
+        },
+    }, async (input) => (0, mcp_1.runTool)("write_beats_file", () => runWriteBeatsFile(input)));
+}

package/dist/util.d.ts

@@ -0,0 +1,43 @@
+export declare function resolveProjectRoot(projectRoot?: string): string;
+/**
+ * Validates a value used as a single path segment (project/video name, beat id)
+ * before it's joined into any filesystem path or process argv. Rejects `..`,
+ * `/`, `\`, and anything else outside a conservative safe set.
+ */
+export declare function sanitizeSegment(value: string, label: string): string;
+/**
+ * PascalCases an id for use as a component/file name: split on any run of
+ * non-alphanumeric characters, capitalize the first letter of each remaining
+ * segment, join. A result starting with a digit gets an "S" prefix (invalid
+ * JS identifier otherwise); an empty result (all-symbol id) falls back to "Scene".
+ * scaffold_scene and stitch_composition both call this, so a beat's scene file name
+ * and its import in the generated composition always agree.
+ */
+export declare function pascalCase(id: string): string;
+/**
+ * Validates a path argument that will be handed to a spawned child process
+ * (npx/ffmpeg): no shell metacharacters, and must resolve inside `root` so a
+ * crafted `../../` can't point the command at an arbitrary filesystem location.
+ */
+export declare function sanitizeRelativeOutPath(root: string, relPath: string, label: string): string;
+/**
+ * Copies a directory tree, skipping any `node_modules` subtree and never
+ * overwriting a file that already exists at the destination -- used by
+ * init_project to lay the bundled template shell into a user's project without
+ * clobbering anything the dev (or a prior init_project call, for a second video
+ * in the same project) has already touched.
+ */
+export declare function copyTemplateTree(src: string, dest: string): void;
+export interface SpawnResult {
+    code: number | null;
+    stdout: string;
+    stderr: string;
+}
+/**
+ * Runs a child process to completion and captures its stdout/stderr in memory.
+ * `spawn` with an argv array, never `exec`/`execSync` with an interpolated shell string --
+ * render_video and qc_extract_frames both go through this. Capturing the child's output
+ * here has nothing to do with *this* process's own stdout (the MCP transport); it's
+ * returned as normal tool-result content by the caller.
+ */
+export declare function spawnCapture(command: string, args: string[], cwd: string): Promise<SpawnResult>;