@openvidstudio/mcp-server 0.1.0 → 1.4.0

package/dist/tools/writeDescription.js

@@ -0,0 +1,503 @@
+"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.MIN_CHAPTER_SECONDS = exports.MIN_CHAPTERS = void 0;
+exports.humanizeBeatId = humanizeBeatId;
+exports.chapterTimestamp = chapterTimestamp;
+exports.buildChapters = buildChapters;
+exports.runWriteDescription = runWriteDescription;
+exports.registerWriteDescription = registerWriteDescription;
+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 stitchComposition_1 = require("./stitchComposition");
+/** YouTube lists chapters only when there are at least three and each is at least ten seconds. */
+exports.MIN_CHAPTERS = 3;
+exports.MIN_CHAPTER_SECONDS = 10;
+/**
+ * Reads brief.json if present. Absence is normal, not an error: a literal/quick video can skip
+ * write_brief entirely, and this tool must still work without it (just without logline/audience/
+ * feeling/shot-disclosure framing).
+ *
+ * Presence with a malformed shotList entry is not tolerated the same way: silently skipping a
+ * shot this tool can't classify as real or constructed would be exactly the silent-disclosure-
+ * loss this tool exists to prevent, so a shape violation throws instead of being filtered out
+ * quietly. Only shots with real === false are collected; a shot with real === true needs no
+ * disclosure and its provenance/focalPoint are write_brief's concern, not read here.
+ */
+function readBrief(projectRoot, videoName) {
+    const briefPath = path.join(projectRoot, "src", "videos", videoName, "brief.json");
+    if (!fs.existsSync(briefPath))
+        return undefined;
+    let raw;
+    try {
+        raw = JSON.parse(fs.readFileSync(briefPath, "utf8"));
+    }
+    catch (err) {
+        throw new Error(`Failed to parse ${briefPath}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    const logline = typeof raw.logline === "string" && raw.logline.trim().length > 0 ? raw.logline.trim() : undefined;
+    const audience = typeof raw.audience === "string" && raw.audience.trim().length > 0 ? raw.audience.trim() : undefined;
+    const feeling = typeof raw.feeling === "string" && raw.feeling.trim().length > 0 ? raw.feeling.trim() : undefined;
+    const constructedShots = [];
+    // A lesson is constructed on purpose, all of it: there is no real product being imitated, so there is
+    // no per-shot disclosure to collect (the description carries one line saying so instead).
+    const lesson = raw.mode === "supernova";
+    if (!lesson && raw.shotList !== undefined) {
+        if (!Array.isArray(raw.shotList)) {
+            throw new Error(`${briefPath}: "shotList" must be an array if present.`);
+        }
+        const rawShots = raw.shotList;
+        rawShots.forEach((shot, i) => {
+            if (typeof shot !== "object" || shot === null) {
+                throw new Error(`${briefPath}: shotList[${i}] is not an object.`);
+            }
+            const s = shot;
+            if (typeof s.beatId !== "string" || s.beatId.length === 0) {
+                throw new Error(`${briefPath}: shotList[${i}] is missing a valid "beatId".`);
+            }
+            if (typeof s.real !== "boolean") {
+                // Can't safely treat an unclassified shot as real (that would silently skip a
+                // disclosure it might owe), so this is a hard error rather than a default.
+                throw new Error(`${briefPath}: shotList[${i}] ("${s.beatId}") is missing a boolean "real".`);
+            }
+            if (s.real === true)
+                return; // A real capture needs no disclosure.
+            if (typeof s.provenance !== "string" || s.provenance.trim().length === 0) {
+                throw new Error(`${briefPath}: shotList[${i}] ("${s.beatId}", real: false) is missing "provenance".`);
+            }
+            if (typeof s.whyConstructed !== "string" || s.whyConstructed.trim().length === 0) {
+                throw new Error(`${briefPath}: shotList[${i}] ("${s.beatId}", real: false) is missing "whyConstructed".`);
+            }
+            constructedShots.push({
+                beatId: s.beatId,
+                provenance: s.provenance.trim(),
+                whyConstructed: s.whyConstructed.trim(),
+            });
+        });
+    }
+    // sampleContent: beats whose real capture is of a sample app, dataset or repo built to be filmed.
+    // write_brief documents these as surfacing in the description, so they are disclosed here exactly
+    // like a constructed shot. A malformed entry throws for the same reason a malformed shot does.
+    if (raw.sampleContent !== undefined) {
+        if (!Array.isArray(raw.sampleContent)) {
+            throw new Error(`${briefPath}: "sampleContent" must be an array if present.`);
+        }
+        raw.sampleContent.forEach((entry, i) => {
+            if (typeof entry !== "object" || entry === null) {
+                throw new Error(`${briefPath}: sampleContent[${i}] is not an object.`);
+            }
+            const e = entry;
+            for (const key of ["beatId", "whatItIs", "whyConstructed"]) {
+                if (typeof e[key] !== "string" || e[key].trim().length === 0) {
+                    throw new Error(`${briefPath}: sampleContent[${i}] is missing "${key}".`);
+                }
+            }
+            constructedShots.push({
+                beatId: e.beatId.trim(),
+                provenance: e.whatItIs.trim(),
+                whyConstructed: e.whyConstructed.trim(),
+            });
+        });
+    }
+    return { logline, audience, feeling, constructedShots, ...(lesson ? { lesson: true } : {}) };
+}
+/**
+ * A lesson's concept card (src/videos/<video>/concept.json) gives the practice question and its answer. Absence is
+ * normal: most lessons have no practice question, and then nothing here changes. It counts only when both the question
+ * and the answer are there, because a question with no answer to withhold is just a line in the narration.
+ */
+function readPractice(projectRoot, videoName) {
+    const file = path.join(projectRoot, "src", "videos", videoName, "concept.json");
+    if (!fs.existsSync(file))
+        return undefined;
+    let card;
+    try {
+        card = JSON.parse(fs.readFileSync(file, "utf8"));
+    }
+    catch (err) {
+        throw new Error(`Failed to parse ${file}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    const text = (v) => (typeof v === "string" && v.trim().length > 0 ? v.trim() : undefined);
+    const question = text(card.practiceQuestion);
+    const answer = text(card.answer);
+    if (!question || !answer)
+        return undefined;
+    return { question, answer, working: text(card.answerWorking) };
+}
+/** The pinned comment: the answer, and one line of working when the card has it. */
+function buildAnswer(practice) {
+    const lines = [`Answer: ${practice.answer}`];
+    if (practice.working)
+        lines.push(`Working: ${practice.working}`);
+    return lines.join("\n") + "\n";
+}
+/**
+ * Reads beats.json for the real beat list. Required, unlike brief.json: without it there is
+ * nothing to ground the description in, which is the entire point of this tool.
+ */
+function readBeats(projectRoot, videoName) {
+    const beatsPath = path.join(projectRoot, "src", "videos", videoName, "beats.json");
+    if (!fs.existsSync(beatsPath)) {
+        throw new Error(`No beats.json at ${beatsPath}. Run write_beats_file first.`);
+    }
+    const doc = JSON.parse(fs.readFileSync(beatsPath, "utf8"));
+    const fps = typeof doc.fps === "number" && doc.fps > 0 ? doc.fps : 30;
+    if (!Array.isArray(doc.beats)) {
+        throw new Error(`${beatsPath}: "beats" must be an array.`);
+    }
+    const rawBeats = doc.beats;
+    const beats = rawBeats.map((raw, i) => {
+        if (typeof raw !== "object" || raw === null) {
+            throw new Error(`${beatsPath}: beat[${i}] is not an object.`);
+        }
+        const b = raw;
+        return {
+            id: typeof b.id === "string" && b.id.length > 0 ? b.id : `beat-${i}`,
+            duration: typeof b.duration === "number" && b.duration > 0 ? b.duration : 0,
+            vo: typeof b.vo === "string" ? b.vo : "",
+            chapter: typeof b.chapter === "string" && b.chapter.trim().length > 0 ? b.chapter.trim() : undefined,
+        };
+    });
+    return { fps, beats };
+}
+/** "demo-search" -> "Demo search". A beat id is a slug, not a title, but it is the only name a beat has by default. */
+function humanizeBeatId(id) {
+    const spaced = id.replace(/[-_]+/g, " ").trim();
+    return spaced.length === 0 ? id : spaced[0].toUpperCase() + spaced.slice(1);
+}
+/** 75 -> "1:15", 3725 -> "1:02:05". YouTube reads m:ss, or h:mm:ss from an hour on. */
+function chapterTimestamp(seconds) {
+    const total = Math.max(0, Math.floor(seconds));
+    const h = Math.floor(total / 3600);
+    const m = Math.floor((total % 3600) / 60);
+    const s = total % 60;
+    const pad = (n) => String(n).padStart(2, "0");
+    return h > 0 ? `${h}:${pad(m)}:${pad(s)}` : `${m}:${pad(s)}`;
+}
+/**
+ * Chapters from the real beats, in YouTube's terms: the first at 0:00, each at least ten seconds,
+ * at least three of them. Beats are merged forward into one chapter until it reaches ten seconds
+ * (named after its first beat), and a short tail folds into the chapter before it, so a video of
+ * many two-second beats still gets sensible chapters. Fewer than three chapters means YouTube
+ * would ignore the list, so none are written and the caller says why instead.
+ */
+function buildChapters(beats, fps) {
+    const timed = beats.filter((b) => b.duration > 0);
+    const groups = [];
+    let cursor = 0;
+    for (const beat of timed) {
+        const seconds = beat.duration / fps;
+        const open = groups[groups.length - 1];
+        if (open && open.length < exports.MIN_CHAPTER_SECONDS) {
+            open.length += seconds;
+        }
+        else {
+            groups.push({ start: cursor, length: seconds, label: beat.chapter ?? humanizeBeatId(beat.id) });
+        }
+        cursor += seconds;
+    }
+    const last = groups[groups.length - 1];
+    if (groups.length > 1 && last && last.length < exports.MIN_CHAPTER_SECONDS) {
+        groups.pop();
+        groups[groups.length - 1].length += last.length;
+    }
+    const totalSeconds = cursor;
+    if (groups.length < exports.MIN_CHAPTERS) {
+        return {
+            chapters: [],
+            skippedBecause: `YouTube lists chapters only when there are at least ${exports.MIN_CHAPTERS} and each is ${exports.MIN_CHAPTER_SECONDS} seconds or more, and this ` +
+                `${totalSeconds.toFixed(0)}-second video makes ${groups.length}.`,
+        };
+    }
+    return { chapters: groups.map((g) => ({ seconds: g.start, label: g.label })) };
+}
+/**
+ * The credit lines this video actually owes, read from what is on disk rather than assumed:
+ * the tool, the music (generated, imported with its provenance, or built in), narration, and any
+ * sound effect whose licence asks for a credit (ATTRIBUTION.md, which plan_sound_effects writes).
+ */
+function buildCredits(projectRoot, videoName, beats) {
+    const credits = [
+        "Made with openvidstudio (https://github.com/AnayDhawan/openvidstudio), an open-source video pipeline for software projects.",
+    ];
+    const videoDir = path.join(projectRoot, "src", "videos", videoName);
+    const layer = (0, stitchComposition_1.readExistingMusicLayer)(path.join(videoDir, `${(0, util_1.pascalCase)(videoName)}Demo.tsx`));
+    if (layer) {
+        const audioDir = path.join(projectRoot, "public", "audio");
+        const stem = layer.file.replace(/\.[^.]+$/, "");
+        const readJson = (file) => {
+            try {
+                return JSON.parse(fs.readFileSync(file, "utf8"));
+            }
+            catch {
+                return null;
+            }
+        };
+        const provenance = readJson(path.join(audioDir, `${layer.file}.source.json`));
+        const cues = readJson(path.join(audioDir, `${stem}.cues.json`));
+        if (provenance && typeof provenance.title === "string") {
+            const repo = typeof provenance.sourceRepo === "string" ? ` from ${provenance.sourceRepo}` : "";
+            const licence = typeof provenance.licence === "string" ? ` (${provenance.licence})` : "";
+            credits.push(`Music: "${provenance.title}"${repo}${licence}.`);
+        }
+        else if (cues?.source === "generated") {
+            credits.push("Music: an original score composed for this video with openvidstudio's compose_score. Pure synthesis, no samples, nothing to license.");
+        }
+        else if (layer.file === "music-bed.mp3") {
+            credits.push("Music: a bed synthesized by openvidstudio's built-in generator. No samples, nothing to license.");
+        }
+        else {
+            credits.push(`Music: ${layer.file} (its source was not recorded in this project, so add the credit by hand).`);
+        }
+    }
+    if (beats.some((b) => b.vo.trim().length > 0)) {
+        try {
+            const { engine, voice } = (0, config_1.loadConfig)(projectRoot).narration;
+            credits.push(`Narration: synthesized speech (${engine}, voice ${voice}).`);
+        }
+        catch {
+            credits.push("Narration: synthesized speech.");
+        }
+    }
+    const attribution = path.join(projectRoot, "public", "imported_audios", "ATTRIBUTION.md");
+    if (fs.existsSync(attribution)) {
+        const rows = fs
+            .readFileSync(attribution, "utf8")
+            .split(/\r?\n/)
+            .filter((l) => l.startsWith("| ") && !l.startsWith("| File") && !/^\|[-| ]+\|$/.test(l))
+            .map((l) => l.split("|").map((c) => c.trim()).filter(Boolean))
+            .filter((cols) => cols.length >= 2);
+        for (const cols of rows) {
+            const [file, source, author, licence] = cols;
+            credits.push(`Sound effect ${file}: ${[source, author, licence].filter(Boolean).join(", ")}. The licence asks for this credit.`);
+        }
+    }
+    return credits;
+}
+/** ["a"] -> "a", ["a", "b"] -> "a and b", ["a", "b", "c"] -> "a, b and c". */
+function joinNames(names) {
+    return names.length <= 1 ? (names[0] ?? "") : `${names.slice(0, -1).join(", ")} and ${names[names.length - 1]}`;
+}
+function formatSeconds(frames, fps) {
+    const rounded = Math.round((frames / fps) * 10) / 10;
+    return rounded % 1 === 0 ? `${rounded}s` : `${rounded.toFixed(1)}s`;
+}
+/**
+ * Builds the markdown body. Pure string assembly, no LLM call: this server doesn't call one for
+ * any tool, so "drafting" here means template logic over real facts (brief fields, real beats),
+ * never invented content.
+ */
+function buildDescription(videoName, brief, beatsData, chapters, credits, lesson = false, practice, disclaimers = []) {
+    const { fps, beats } = beatsData;
+    const totalFrames = beats.reduce((sum, b) => sum + b.duration, 0);
+    const lines = [`# ${videoName}`, ""];
+    const firstVo = beats.find((b) => b.vo.trim().length > 0)?.vo.trim();
+    if (brief?.logline) {
+        lines.push(brief.logline);
+    }
+    else if (firstVo) {
+        lines.push(firstVo);
+    }
+    else {
+        lines.push(`${videoName}: ${beats.length} beat${beats.length === 1 ? "" : "s"}, no narration recorded yet.`);
+    }
+    lines.push("");
+    lines.push(`Length: ${formatSeconds(totalFrames, fps)} across ${beats.length} beat${beats.length === 1 ? "" : "s"}.`);
+    if (brief?.audience) {
+        lines.push(`Made for: ${brief.audience}.`);
+    }
+    if (brief?.feeling) {
+        lines.push(`Intended feeling: ${brief.feeling}.`);
+    }
+    lines.push("");
+    if (chapters.chapters.length > 0) {
+        lines.push("## Chapters");
+        lines.push("");
+        for (const c of chapters.chapters)
+            lines.push(`${chapterTimestamp(c.seconds)} ${c.label}`);
+        lines.push("");
+    }
+    else if (chapters.skippedBecause) {
+        lines.push(`Chapters left out: ${chapters.skippedBecause}`);
+        lines.push("");
+    }
+    if (beats.length > 0) {
+        lines.push("## What this video shows");
+        lines.push("");
+        for (const beat of beats) {
+            const narration = beat.vo.trim().length > 0 ? beat.vo.trim() : "(no narration recorded for this beat)";
+            lines.push(`- **${beat.id}** (${formatSeconds(beat.duration, fps)}): ${narration}`);
+        }
+        lines.push("");
+    }
+    const constructedShots = brief?.constructedShots ?? [];
+    if (lesson) {
+        // Replaces the sample-content disclosure: everything in a lesson is drawn for it.
+        lines.push("This video is a constructed explanation, not footage.");
+        lines.push("");
+        if (practice) {
+            lines.push("## Practice question");
+            lines.push("");
+            lines.push(practice.question);
+            lines.push("");
+            lines.push("Drop your answer in the comments.");
+            lines.push("");
+        }
+    }
+    else if (constructedShots.length > 0) {
+        lines.push("## Sample content used in this video");
+        lines.push("");
+        // One sentence per distinct disclosure: six beats filmed from the same sample app are one fact
+        // told once, with every beat named, not the same sentence six times.
+        const groups = new Map();
+        for (const shot of constructedShots) {
+            const key = `${shot.provenance}\u0000${shot.whyConstructed}`;
+            const group = groups.get(key) ?? { provenance: shot.provenance, whyConstructed: shot.whyConstructed, beatIds: [] };
+            if (!group.beatIds.includes(shot.beatId))
+                group.beatIds.push(shot.beatId);
+            groups.set(key, group);
+        }
+        for (const group of groups.values()) {
+            const names = group.beatIds.length === 1 ? `The ${group.beatIds[0]} segment` : `The ${joinNames(group.beatIds)} segments`;
+            lines.push(`${names} ${group.beatIds.length === 1 ? "shows" : "show"} ${group.provenance}. It was built specifically for ` +
+                `this video, not captured from the real product, because ${group.whyConstructed}.`);
+            lines.push("");
+        }
+    }
+    lines.push("## Credits");
+    lines.push("");
+    for (const c of credits)
+        lines.push(`- ${c}`);
+    lines.push("");
+    // Last, each line once: a line the description already carries on its own is not repeated.
+    const body = new Set(lines.map((l) => l.trim()));
+    const added = disclaimers.filter((d) => !body.has(d));
+    for (const d of added)
+        lines.push(d);
+    if (added.length > 0)
+        lines.push("");
+    return lines.join("\n").replace(/\n{3,}/g, "\n\n").trimEnd() + "\n";
+}
+/**
+ * Writes output/<videoName>-DESCRIPTION.md and refuses to report success if a constructed
+ * shot's disclosure went missing from the file it just wrote (see the round-trip check below).
+ * See ShotListEntry/readBrief above for the brief.json shape this reads.
+ */
+function runWriteDescription(input) {
+    const videoName = (0, util_1.sanitizeSegment)(input.videoName, "videoName");
+    const projectRoot = (0, util_1.resolveProjectRoot)(input.projectRoot);
+    const brief = readBrief(projectRoot, videoName);
+    const beatsData = readBeats(projectRoot, videoName);
+    const chapters = buildChapters(beatsData.beats, beatsData.fps);
+    const credits = buildCredits(projectRoot, videoName, beatsData.beats);
+    const lesson = brief?.lesson === true || (0, config_1.productionMode)((0, config_1.loadConfig)(projectRoot)) === "supernova";
+    const practice = lesson ? readPractice(projectRoot, videoName) : undefined;
+    const disclaimers = lesson
+        ? [...new Set(((0, config_1.loadConfig)(projectRoot).disclaimers ?? []).map((d) => d.trim()).filter((d) => d.length > 0))]
+        : [];
+    const content = buildDescription(videoName, brief, beatsData, chapters, credits, lesson, practice, disclaimers);
+    const outPath = path.join(projectRoot, "output", `${videoName}-DESCRIPTION.md`);
+    fs.mkdirSync(path.dirname(outPath), { recursive: true });
+    fs.writeFileSync(outPath, content, "utf8");
+    const constructedShots = lesson ? [] : (brief?.constructedShots ?? []);
+    if (constructedShots.length > 0) {
+        // Round-trip: read back what actually landed on disk and confirm every disclosure survived,
+        // rather than trusting the string already held in memory. A dropped disclosure is a bug in
+        // buildDescription, not a cosmetic gap, so it throws with the half-written file removed,
+        // never a silently "successful" result.
+        const writtenBack = fs.readFileSync(outPath, "utf8");
+        const missing = constructedShots.filter((shot) => !writtenBack.includes(shot.provenance) || !writtenBack.includes(shot.whyConstructed));
+        if (missing.length > 0) {
+            try {
+                fs.unlinkSync(outPath);
+            }
+            catch {
+                // Best-effort cleanup only; the error below is the one that matters.
+            }
+            throw new Error(`write_description internal error: the disclosure for ${missing.map((s) => s.beatId).join(", ")} is ` +
+                `missing from the file this call just wrote. This is a bug in the description template, not a ` +
+                `passing result, so the incomplete file was removed instead of being reported as written.`);
+        }
+    }
+    let answerPath;
+    if (practice) {
+        answerPath = path.join(projectRoot, "output", `${videoName}-ANSWER.md`);
+        fs.writeFileSync(answerPath, buildAnswer(practice), "utf8");
+    }
+    return {
+        written: true,
+        path: outPath,
+        sampleContentDisclosed: constructedShots.map((s) => s.beatId),
+        chapters: chapters.chapters.map((c) => `${chapterTimestamp(c.seconds)} ${c.label}`),
+        credits,
+        ...(practice && answerPath ? { answerPath, practiceQuestion: practice.question } : {}),
+        ...(disclaimers.length > 0 ? { disclaimers } : {}),
+    };
+}
+function registerWriteDescription(server) {
+    server.registerTool("write_description", {
+        title: "Write a video's description, with sample content disclosed",
+        description: "Writes output/<videoName>-DESCRIPTION.md: a short description of the video grounded in its real " +
+            "beats.json (beat list and narration, never invented), plus brief.json's logline/audience/feeling if " +
+            "that file exists. brief.json is optional -- a literal/quick video that skipped write_brief works " +
+            "fine without one -- but beats.json is required, since there is otherwise nothing to describe. " +
+            "brief.json's shotList carries the real/constructed split: every shot with real: false is disclosed " +
+            "in plain language in its own section, naming which beat it is, what was built instead of the real " +
+            "product (provenance), and why (whyConstructed). That disclosure is never silently dropped: after " +
+            "writing, the tool reads its own output back and throws rather than returning success if any " +
+            "constructed shot's disclosure is missing from it, removing the incomplete file instead of leaving " +
+            "it on disk. The file is YouTube-ready: a Chapters list built from the beats (first at 0:00, each at " +
+            "least ten seconds, merging short beats forward; a beat may carry an optional `chapter` title, " +
+            "otherwise its id is made readable; under three chapters it says why they were left out instead of " +
+            "writing a list YouTube would ignore), and a Credits section read from what is on disk: the tool, " +
+            "the music (an original compose_score track, an imported CC0 track with its source, or the built-in " +
+            "bed), narration engine and voice, and any sound effect whose licence asks for a credit. " +
+            "For a lesson (Supernova mode) whose concept card (src/videos/<videoName>/concept.json) has a practiceQuestion " +
+            "and an answer, the description gains a Practice question section with the question and the line " +
+            "\"Drop your answer in the comments.\", and the answer goes only to output/<videoName>-ANSWER.md (a ready-to-paste " +
+            "pinned comment: the answer, plus a line of working from the card's optional answerWorking), returned as answerPath. " +
+            "The `disclaimers` string array in openvidstudio.config.json is appended to every lesson description, each line " +
+            "once, at the end. A project without these fields gets the same file as before. " +
+            "finalize_video writes this file on every run, so a finished video always has one.",
+        inputSchema: {
+            projectRoot: zod_1.z.string().optional(),
+            videoName: zod_1.z.string().min(1),
+        },
+    }, async (input) => (0, mcp_1.runTool)("write_description", () => runWriteDescription(input)));
+}

package/dist/util.d.ts

@@ -27,17 +27,12 @@ export declare function sanitizeRelativeOutPath(root: string, relPath: string, l
  * 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;
-}
+export declare function copyTemplateTree(src: string, dest: string, skip?: (relativePath: string) => boolean, base?: string): void;
 /**
- * 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.
+ * Child-process spawning now lives in @openvidstudio/capture, which owns every code path
+ * that shells out. Re-exported here because roughly twenty call sites in this package
+ * import it from "../util", and the boundary that moved is a packaging boundary, not a
+ * call-site one.
  */
-export declare function spawnCapture(command: string, args: string[], cwd: string): Promise<SpawnResult>;
+export { spawnCapture } from "@openvidstudio/capture";
+export type { SpawnResult } from "@openvidstudio/capture";

package/dist/util.js

@@ -33,15 +33,14 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.spawnCapture = void 0;
 exports.resolveProjectRoot = resolveProjectRoot;
 exports.sanitizeSegment = sanitizeSegment;
 exports.pascalCase = pascalCase;
 exports.sanitizeRelativeOutPath = sanitizeRelativeOutPath;
 exports.copyTemplateTree = copyTemplateTree;
-exports.spawnCapture = spawnCapture;
 const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
-const node_child_process_1 = require("node:child_process");
 function resolveProjectRoot(projectRoot) {
     return projectRoot ? path.resolve(projectRoot) : process.cwd();
 }
@@ -73,9 +72,9 @@ function pascalCase(id) {
 }
 // Blocks shell metacharacters relevant on POSIX (;&|`$<>) and on Windows cmd.exe
 // specifically (%^"), which matters here because render_video spawns npx.cmd --
-// Windows can only execute a .cmd/.bat file via cmd.exe, and spawnCapture (below)
-// explicitly routes that one case through shell:true, so cmd.exe's own
-// metacharacters are in scope for any argument reaching that spawn call.
+// Windows can only execute a .cmd/.bat file via cmd.exe, and @openvidstudio/capture's
+// spawnCapture routes that one case through shell:true, so cmd.exe's own metacharacters
+// are in scope for any argument reaching that spawn call.
 const DANGEROUS_CHARS = /[;&|`$<>\n\r%^"]/;
 /**
  * Validates a path argument that will be handed to a spawned child process
@@ -100,7 +99,7 @@ function sanitizeRelativeOutPath(root, relPath, label) {
  * clobbering anything the dev (or a prior init_project call, for a second video
  * in the same project) has already touched.
  */
-function copyTemplateTree(src, dest) {
+function copyTemplateTree(src, dest, skip, base = src) {
     if (!fs.existsSync(src)) {
         throw new Error(`Template directory not found at ${src}. This package's build step (scripts/copy-template.mjs) may not have run.`);
     }
@@ -110,54 +109,21 @@ function copyTemplateTree(src, dest) {
             continue;
         const s = path.join(src, entry.name);
         const d = path.join(dest, entry.name);
+        if (skip?.(path.relative(base, s).split(path.sep).join("/")))
+            continue;
         if (entry.isDirectory()) {
-            copyTemplateTree(s, d);
+            copyTemplateTree(s, d, skip, base);
         }
         else if (!fs.existsSync(d)) {
             fs.copyFileSync(s, d);
         }
     }
 }
-// On Windows, spawning a `.cmd`/`.bat` shim (npx.cmd, the only such command any caller of
-// spawnCapture ever passes -- ffmpeg/ffprobe are real .exe) with shell:false throws a
-// synchronous EINVAL: CreateProcess cannot launch a batch file directly, and (verified
-// against this repo's actual Node runtime, Task 4's real end-to-end pipeline run) Node's
-// spawn() does not transparently shell out for it the way an older assumption in this file
-// believed. shell:true routes exactly that one case through cmd.exe, which is also why
-// sanitizeRelativeOutPath/sanitizeSegment already block shell metacharacters including `%^"`
-// (cmd.exe's own specials) everywhere a value can reach this function -- that defense was
-// already written for a cmd.exe hop, this just makes the hop actually happen for the case
-// that needs it, without changing behavior for the real-.exe (ffmpeg/ffprobe) callers.
-const WINDOWS_SHIM_RE = /\.(cmd|bat)$/i;
 /**
- * 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.
+ * Child-process spawning now lives in @openvidstudio/capture, which owns every code path
+ * that shells out. Re-exported here because roughly twenty call sites in this package
+ * import it from "../util", and the boundary that moved is a packaging boundary, not a
+ * call-site one.
  */
-function spawnCapture(command, args, cwd) {
-    return new Promise((resolve, reject) => {
-        const shell = process.platform === "win32" && WINDOWS_SHIM_RE.test(command);
-        // Node's own shell:true + args-array combination does NOT escape/quote args for the
-        // caller (it just concatenates them into one command line before handing it to
-        // cmd.exe -- Node emits DEP0190 warning about exactly this), so an argument containing
-        // a space (a legal, unsanitized character in e.g. outPathRel) would silently word-split
-        // into two argv entries once shell:true is in effect. Every arg that reaches this
-        // function is already filtered through DANGEROUS_CHARS/SAFE_SEGMENT, which blocks `"`
-        // itself, so wrapping each in double quotes here is always safe and closes that gap
-        // without touching the non-shell (ffmpeg/ffprobe) call path at all.
-        const finalArgs = shell ? args.map((a) => `"${a}"`) : args;
-        const child = (0, node_child_process_1.spawn)(command, finalArgs, { cwd, shell });
-        let stdout = "";
-        let stderr = "";
-        child.stdout?.on("data", (chunk) => {
-            stdout += chunk.toString();
-        });
-        child.stderr?.on("data", (chunk) => {
-            stderr += chunk.toString();
-        });
-        child.on("error", reject);
-        child.on("close", (code) => resolve({ code, stdout, stderr }));
-    });
-}
+var capture_1 = require("@openvidstudio/capture");
+Object.defineProperty(exports, "spawnCapture", { enumerable: true, get: function () { return capture_1.spawnCapture; } });