@openvidstudio/mcp-server 0.1.0 → 1.3.1

package/dist/tools/captureTerminal.js

@@ -0,0 +1,156 @@
+"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.runCaptureTerminal = runCaptureTerminal;
+exports.registerCaptureTerminal = registerCaptureTerminal;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const zod_1 = require("zod");
+const util_1 = require("../util");
+const capture_1 = require("@openvidstudio/capture");
+const mcp_1 = require("./mcp");
+const facts_1 = require("../facts");
+const stepSchema = zod_1.z.discriminatedUnion("type", [
+    zod_1.z.object({ type: zod_1.z.literal("type"), text: zod_1.z.string() }),
+    zod_1.z.object({ type: zod_1.z.literal("wait"), ms: zod_1.z.number().int().positive() }),
+]);
+async function runCaptureTerminal(input) {
+    const result = await captureTerminal(input);
+    const projectRoot = (0, util_1.resolveProjectRoot)(input.projectRoot);
+    (0, facts_1.writeFactRecord)(projectRoot, {
+        tool: "capture_terminal",
+        beatId: (0, util_1.sanitizeSegment)(input.beatId, "beatId"),
+        facts: {
+            kind: "real-capture",
+            outPath: (0, facts_1.relToProject)(projectRoot, result.outPath),
+            bytes: (0, facts_1.fileBytes)(result.outPath),
+            command: [input.command, ...(input.args ?? [])].join(" "),
+            exitCode: result.exitCode,
+            durationMs: result.durationMs,
+            eventCount: result.eventCount,
+            mode: result.mode,
+            truncated: result.truncated,
+        },
+    });
+    return result;
+}
+async function captureTerminal(input) {
+    const beatId = (0, util_1.sanitizeSegment)(input.beatId, "beatId");
+    const projectRoot = (0, util_1.resolveProjectRoot)(input.projectRoot);
+    const outPathRel = input.outPath ?? path.join("public", "terminal", `${beatId}.json`);
+    (0, util_1.sanitizeRelativeOutPath)(projectRoot, outPathRel, "outPath");
+    const outPathAbs = path.join(projectRoot, outPathRel);
+    fs.mkdirSync(path.dirname(outPathAbs), { recursive: true });
+    const { cast, truncated, mode, warnings } = await (0, capture_1.recordTerminal)({
+        command: input.command,
+        args: input.args,
+        cwd: input.cwd ? path.resolve(projectRoot, input.cwd) : projectRoot,
+        script: input.script,
+        cols: input.cols,
+        rows: input.rows,
+        timeoutMs: input.timeoutSeconds === undefined ? undefined : input.timeoutSeconds * 1000,
+        mode: input.mode,
+        maxOutputChars: input.maxOutputChars,
+    });
+    fs.writeFileSync(outPathAbs, JSON.stringify(cast, null, 2) + "\n", "utf8");
+    return {
+        outPath: outPathAbs,
+        durationMs: cast.durationMs,
+        exitCode: cast.exitCode,
+        eventCount: cast.events.length,
+        cols: cast.cols,
+        rows: cast.rows,
+        truncated,
+        mode,
+        ...(() => {
+            const notes = [
+                ...(mode === "pipe" && input.mode !== "pipe"
+                    ? [
+                        "Recorded through pipes, not a pty, because node-pty is not installed here. Most CLIs suppress " +
+                            "colour when no terminal is attached, so this cast is likely duller than the real run. Install " +
+                            "node-pty in this project for a faithful recording, or use capture_desktop against the terminal " +
+                            "window for a full-screen TUI.",
+                    ]
+                    : []),
+                ...warnings,
+            ];
+            return notes.length > 0 ? { note: notes.join(" ") } : {};
+        })(),
+    };
+}
+function registerCaptureTerminal(server) {
+    server.registerTool("capture_terminal", {
+        title: "Record a real command run as timed, themeable text",
+        description: "Records a CLI tool actually running, for the large category of software that has no URL and no window " +
+            "worth filming: agents, build tools, package managers, anything whose demo is a terminal. Runs the " +
+            "command with an argv array (never a shell string), timestamps every output chunk, optionally drives " +
+            "its stdin from a `script` of type/wait steps, and writes a JSON cast to " +
+            "public/terminal/<beatId>.json. Recording text rather than pixels is the point: the result is " +
+            "resolution-independent, picks up the palette extract_brand resolved, and replays through the " +
+            "TerminalReplay component in @openvidstudio/core, so one capture renders crisply at any size instead of " +
+            "baking in one machine's font and theme. When the optional node-pty module is installed it allocates a " +
+            "real pty, so the program keeps its colour and cursor addressing and a full-screen TUI records " +
+            "faithfully; otherwise it falls back to piped stdout/stderr, which needs no native build but makes most " +
+            "CLIs disable colour. The mode used is returned and stored in the cast. Output is capped at 20k events " +
+            "and 4MB and reports `truncated` rather than exhausting memory on a runaway process. Pass "
+            + "maxOutputChars to bound it deliberately: a command whose real output runs to six figures "
+            + "produces a cast nothing can replay inside a beat, and cutting it at capture time keeps the "
+            + "cast and the video the same thing, which trimming the file afterwards would not.",
+        inputSchema: {
+            projectRoot: zod_1.z.string().optional(),
+            beatId: zod_1.z.string().min(1),
+            command: zod_1.z.string().min(1).describe("Executable name only. Arguments go in `args`, never appended here."),
+            args: zod_1.z.array(zod_1.z.string()).optional(),
+            cwd: zod_1.z.string().optional().describe("Working directory, resolved relative to projectRoot."),
+            script: zod_1.z.array(stepSchema).optional().describe("Input to send to the program, as ordered type/wait steps."),
+            cols: zod_1.z.number().int().positive().optional(),
+            rows: zod_1.z.number().int().positive().optional(),
+            timeoutSeconds: zod_1.z.number().positive().optional(),
+            outPath: zod_1.z.string().optional(),
+            maxOutputChars: zod_1.z
+                .number()
+                .int()
+                .positive()
+                .optional()
+                .describe("Record only the first N characters of output and mark the cast truncated. Use it when a command's "
+                + "output is far larger than a beat can replay: the first screenful is what a demo shows anyway."),
+            mode: zod_1.z
+                .enum(["auto", "pty", "pipe"])
+                .optional()
+                .describe("auto (default) uses a pty when node-pty is installed and falls back to pipes. pty fails if it is " +
+                "not installed. pipe never uses one."),
+        },
+    }, async (input) => (0, mcp_1.runTool)("capture_terminal", () => runCaptureTerminal(input)));
+}

package/dist/tools/checkScript.d.ts

@@ -0,0 +1,75 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+/**
+ * A lint for a lesson script (Supernova mode). Mechanical only, no model call: it counts words and
+ * matches patterns, so it can say a sentence is long or a term was never defined, and it cannot say
+ * the explanation is good. A lesson is won or lost on its script, and nothing else in openvidstudio
+ * looks at one; validate_beats checks pacing but not whether the script teaches.
+ *
+ * The rules are SCRIPT.md's lesson script rules: a hook in the first sentence, intuition before
+ * formula, every term defined at first use with at most two new ones a beat, sentences of about 14
+ * words or fewer, maths written as it is spoken, and a check question at the end.
+ */
+export interface ConceptCard {
+    /** What the viewer can do afterwards: "tell why a derivative is a slope". */
+    goal: string;
+    /** The two or three terms that need defining. */
+    terms: string[];
+    /** The running example. */
+    example: string;
+    /**
+     * Where the lesson sits in a syllabus or a series, as it is shown on screen: "IB Physics A.1 Kinematics",
+     * "Part 2 of 4". When set, the opening beat has to say it (see `referenceSpoken`).
+     */
+    reference?: string;
+    /** The reference as it is said aloud: "I B Physics, topic A one, kinematics". The first beat's narration must contain it. */
+    referenceSpoken?: string;
+    /** The longest the lesson may run, in seconds. Default 120. */
+    maxSeconds?: number;
+}
+export type ScriptFindingSeverity = "error" | "warning" | "note";
+export interface ScriptFinding {
+    severity: ScriptFindingSeverity;
+    /** Which check produced it. */
+    check: "sentence-length" | "reading-level" | "glossary" | "new-terms" | "spoken" | "hook" | "pace" | "closing-question" | "length" | "reference";
+    beatId: string;
+    message: string;
+}
+export interface CheckScriptInput {
+    projectRoot?: string;
+    videoName: string;
+    /** Overrides src/videos/<videoName>/beats.json. */
+    beatsJson?: unknown;
+    /** Overrides src/videos/<videoName>/concept.json. */
+    conceptCard?: ConceptCard;
+}
+export interface CheckScriptResult {
+    /** False when any finding is an error. Warnings and notes never fail it. */
+    ok: boolean;
+    beatsChecked: number;
+    findings: ScriptFinding[];
+}
+/** Sentences longer than this on average draw a warning (the target is about 14). */
+export declare const MAX_AVG_SENTENCE_WORDS = 16;
+/** The longest a lesson may run, in seconds, unless its concept card says otherwise. */
+export declare const DEFAULT_MAX_LESSON_SECONDS = 120;
+/** A beat reading above this Flesch-Kincaid grade draws a warning. */
+export declare const MAX_READING_GRADE = 9;
+/** More new terms than this in one beat draws a warning. */
+export declare const MAX_NEW_TERMS_PER_BEAT = 2;
+interface BeatLike {
+    id?: unknown;
+    duration?: unknown;
+    vo?: unknown;
+    scene?: unknown;
+}
+export declare function splitSentences(text: string): string[];
+/** A rough syllable count for English: vowel groups, less a silent final e. Good enough to rank a script, not to be exact. */
+export declare function syllables(word: string): number;
+/** Flesch-Kincaid grade level of a passage. */
+export declare function fleschKincaidGrade(text: string): number;
+/** The `spoken` strings of the Equations in a scene's source. */
+export declare function spokenStrings(source: string): string[];
+export declare function checkScriptLogic(beatsJson: unknown, card: ConceptCard, readScene?: (beat: BeatLike, id: string) => string | null): CheckScriptResult;
+export declare function runCheckScript(input: CheckScriptInput): CheckScriptResult;
+export declare function registerCheckScript(server: McpServer): void;
+export {};

package/dist/tools/checkScript.js

@@ -0,0 +1,279 @@
+"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.MAX_NEW_TERMS_PER_BEAT = exports.MAX_READING_GRADE = exports.DEFAULT_MAX_LESSON_SECONDS = exports.MAX_AVG_SENTENCE_WORDS = void 0;
+exports.splitSentences = splitSentences;
+exports.syllables = syllables;
+exports.fleschKincaidGrade = fleschKincaidGrade;
+exports.spokenStrings = spokenStrings;
+exports.checkScriptLogic = checkScriptLogic;
+exports.runCheckScript = runCheckScript;
+exports.registerCheckScript = registerCheckScript;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const zod_1 = require("zod");
+const util_1 = require("../util");
+const mcp_1 = require("./mcp");
+const validateBeats_1 = require("./validateBeats");
+/** Sentences longer than this on average draw a warning (the target is about 14). */
+exports.MAX_AVG_SENTENCE_WORDS = 16;
+/** The longest a lesson may run, in seconds, unless its concept card says otherwise. */
+exports.DEFAULT_MAX_LESSON_SECONDS = 120;
+/** A beat reading above this Flesch-Kincaid grade draws a warning. */
+exports.MAX_READING_GRADE = 9;
+/** More new terms than this in one beat draws a warning. */
+exports.MAX_NEW_TERMS_PER_BEAT = 2;
+function splitSentences(text) {
+    return text
+        .trim()
+        .split(/(?<=[.!?])\s+/)
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+}
+/** A rough syllable count for English: vowel groups, less a silent final e. Good enough to rank a script, not to be exact. */
+function syllables(word) {
+    const w = word.toLowerCase().replace(/[^a-z]/g, "");
+    if (w.length === 0)
+        return 0;
+    if (w.length <= 3)
+        return 1;
+    const stripped = w.replace(/(?:[^laeiouy]es|[^laeiouy]ed|[^laeiouy]e)$/, "").replace(/^y/, "");
+    const groups = stripped.match(/[aeiouy]{1,2}/g);
+    return Math.max(1, groups ? groups.length : 1);
+}
+/** Flesch-Kincaid grade level of a passage. */
+function fleschKincaidGrade(text) {
+    const sentences = splitSentences(text);
+    const words = text.split(/\s+/).filter((w) => /[a-zA-Z0-9]/.test(w));
+    if (sentences.length === 0 || words.length === 0)
+        return 0;
+    const syl = words.reduce((n, w) => n + (/\d/.test(w) ? 2 : syllables(w)), 0);
+    return 0.39 * (words.length / sentences.length) + 11.8 * (syl / words.length) - 15.59;
+}
+const normalise = (text) => text.toLowerCase().replace(/[^a-z0-9]+/g, " ").trim().replace(/\s+/g, " ");
+const NUMBER_WORDS = /\b(zero|one|two|three|four|five|six|seven|eight|nine|ten|hundred|thousand|million|billion|half|double|twice)\b/i;
+const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+const wordRe = (term) => new RegExp(`(?<![A-Za-z0-9])${escapeRe(term)}(?![A-Za-z0-9])`, "i");
+/** A definition near the term: "a slope is...", "this is called a slope", "slope means...". */
+function definedNear(term, sentences, at) {
+    const t = escapeRe(term);
+    const patterns = [
+        new RegExp(`(?<![A-Za-z0-9])${t}(?![A-Za-z0-9])[^.!?]{0,30}\\b(is|are|means|mean|stands for)\\b`, "i"),
+        new RegExp(`\\b(called|known as|named|we say|we call)\\b[^.!?]{0,20}(?<![A-Za-z0-9])${t}(?![A-Za-z0-9])`, "i"),
+        new RegExp(`(?<![A-Za-z0-9])${t}(?![A-Za-z0-9])[^.!?]{0,6}[,(]\\s*(which|that|or)\\b`, "i"),
+    ];
+    const near = [sentences[at], sentences[at + 1]].filter((s) => typeof s === "string");
+    return near.some((s) => patterns.some((p) => p.test(s)));
+}
+/** The `spoken` strings of the Equations in a scene's source. */
+function spokenStrings(source) {
+    const out = [];
+    const tag = /<Equation\b[\s\S]*?\bspoken\s*=\s*(?:"([^"]*)"|'([^']*)'|\{\s*(?:"([^"]*)"|'([^']*)'|`([^`]*)`)\s*\})/g;
+    for (const m of source.matchAll(tag))
+        out.push(m[1] ?? m[2] ?? m[3] ?? m[4] ?? m[5] ?? "");
+    return out;
+}
+function checkScriptLogic(beatsJson, card, readScene = () => null) {
+    const findings = [];
+    const root = (typeof beatsJson === "object" && beatsJson !== null ? beatsJson : {});
+    const fps = typeof root.fps === "number" && root.fps > 0 ? root.fps : 30;
+    const beats = (Array.isArray(root.beats) ? root.beats : []);
+    const add = (severity, check, beatId, message) => findings.push({ severity, check, beatId, message });
+    const seen = new Set();
+    const spoken = beats.filter((b) => typeof b.vo === "string" && b.vo.length > 0);
+    spoken.forEach((beat, index) => {
+        const id = String(beat.id ?? `beat ${index + 1}`);
+        const vo = beat.vo;
+        const sentences = splitSentences(vo);
+        // sentence length
+        const avg = (0, validateBeats_1.wordCount)(vo) / Math.max(1, sentences.length);
+        if (avg > exports.MAX_AVG_SENTENCE_WORDS) {
+            add("warning", "sentence-length", id, `Sentences average ${avg.toFixed(1)} words, over ${exports.MAX_AVG_SENTENCE_WORDS}. A lesson is heard once; aim for about 14 or fewer and split the long ones.`);
+        }
+        // reading level
+        const grade = fleschKincaidGrade(vo);
+        if (grade > exports.MAX_READING_GRADE) {
+            add("warning", "reading-level", id, `Reads at about grade ${grade.toFixed(1)} (Flesch-Kincaid), above ${exports.MAX_READING_GRADE}. Shorter words and shorter sentences.`);
+        }
+        // glossary: first use, a definition near it, and no more than two new terms a beat
+        const introduced = [];
+        for (const term of card.terms) {
+            const key = term.toLowerCase();
+            if (seen.has(key))
+                continue;
+            const at = sentences.findIndex((s) => wordRe(term).test(s));
+            if (at < 0)
+                continue;
+            seen.add(key);
+            introduced.push(term);
+            if (!definedNear(term, sentences, at)) {
+                add("note", "glossary", id, `"${term}" is first used here with no definition beside it. Say what it is in plain words at first use ("a ${term} is ...").`);
+            }
+        }
+        if (introduced.length > exports.MAX_NEW_TERMS_PER_BEAT) {
+            add("warning", "new-terms", id, `${introduced.length} new terms in one beat (${introduced.join(", ")}). At most ${exports.MAX_NEW_TERMS_PER_BEAT}; spread them over the lesson.`);
+        }
+        // pace against the beat's length: the same budget validate_beats enforces
+        if (typeof beat.duration === "number" && beat.duration > 0) {
+            const pace = (0, validateBeats_1.voPaceCheck)(vo, beat.duration / fps);
+            if (pace.message !== null)
+                add("error", "pace", id, pace.message);
+        }
+        // every Equation's spoken string is in this beat's narration
+        const source = readScene(beat, id);
+        if (source !== null) {
+            const heard = normalise(vo);
+            for (const said of spokenStrings(source)) {
+                if (!heard.includes(normalise(said))) {
+                    add("error", "spoken", id, `The equation's spoken form "${said}" is not in this beat's narration. The voice and the equation must say the same thing.`);
+                }
+            }
+        }
+    });
+    // terms the card names that the narration never mentions
+    for (const term of card.terms) {
+        if (!seen.has(term.toLowerCase()) && spoken.length > 0) {
+            add("warning", "glossary", String(spoken[0].id ?? "beat 1"), `The concept card names "${term}" but no beat's narration mentions it.`);
+        }
+    }
+    // the length: a lesson explains one concept inside its budget (two minutes unless the card says otherwise)
+    const budget = typeof card.maxSeconds === "number" && card.maxSeconds > 0 ? card.maxSeconds : exports.DEFAULT_MAX_LESSON_SECONDS;
+    const total = beats.reduce((n, b) => n + (typeof b.duration === "number" && b.duration > 0 ? b.duration : 0), 0) / fps;
+    if (total > budget + 0.5) {
+        add("error", "length", String(beats[beats.length - 1]?.id ?? "last beat"), `The lesson runs ${total.toFixed(1)} seconds, over its ${budget} second budget. Cut a beat, tighten the derivation, or move the second half to Part 2.`);
+    }
+    // the reference: the opening beat says where this lesson sits (a chapter code, a part number)
+    if (typeof card.reference === "string" && card.reference.trim().length > 0 && spoken.length > 0) {
+        const id = String(spoken[0].id ?? "beat 1");
+        if (typeof card.referenceSpoken !== "string" || card.referenceSpoken.trim().length === 0) {
+            add("warning", "reference", id, `The card gives the reference "${card.reference}" but not how it is said. Add referenceSpoken (for example "I B Physics, topic A one") so the script can be checked for it.`);
+        }
+        else if (!normalise(spoken[0].vo).includes(normalise(card.referenceSpoken))) {
+            add("error", "reference", id, `The opening beat does not say the reference "${card.referenceSpoken}". Tell the viewer where this lesson sits in the first beat.`);
+        }
+    }
+    // the hook: the first beat's first sentence
+    if (spoken.length > 0) {
+        const first = spoken[0];
+        const id = String(first.id ?? "beat 1");
+        const lead = splitSentences(first.vo)[0] ?? "";
+        if (/^\s*in this video\b/i.test(lead)) {
+            add("error", "hook", id, `The script opens "in this video". Open on a question or a surprising fact, not a promise of what is coming.`);
+        }
+        else if (!lead.trim().endsWith("?") && !/\d/.test(lead) && !NUMBER_WORDS.test(lead)) {
+            add("warning", "hook", id, `The first sentence is neither a question nor does it hold a number. The hook is a question or a surprising fact.`);
+        }
+    }
+    // the end: a check question
+    if (spoken.length > 0) {
+        const last = spoken[spoken.length - 1];
+        const lastSentence = splitSentences(last.vo).slice(-1)[0] ?? "";
+        if (!lastSentence.trim().endsWith("?")) {
+            add("error", "closing-question", String(last.id ?? "last beat"), `The last beat does not end with a question. End with a one-line recap, then a check question the viewer can answer in their head.`);
+        }
+    }
+    return { ok: !findings.some((f) => f.severity === "error"), beatsChecked: spoken.length, findings };
+}
+function runCheckScript(input) {
+    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);
+    let beatsJson = input.beatsJson;
+    if (beatsJson === undefined) {
+        const file = path.join(videoDir, "beats.json");
+        if (!fs.existsSync(file))
+            throw new Error(`${file} not found. Write the beats first (write_beats_file), or pass beatsJson.`);
+        beatsJson = JSON.parse(fs.readFileSync(file, "utf8"));
+    }
+    let card = input.conceptCard;
+    if (card === undefined) {
+        const file = path.join(videoDir, "concept.json");
+        if (!fs.existsSync(file)) {
+            throw new Error(`${file} not found. A lesson script is checked against its concept card: write { goal, terms, example } next to beats.json, or pass conceptCard.`);
+        }
+        card = JSON.parse(fs.readFileSync(file, "utf8"));
+    }
+    if (typeof card !== "object" || card === null || typeof card.goal !== "string" || !Array.isArray(card.terms) || typeof card.example !== "string") {
+        throw new Error("The concept card must be { goal: string, terms: string[], example: string } with the optional reference, referenceSpoken and maxSeconds.");
+    }
+    const readScene = (beat, id) => {
+        const rel = typeof beat.scene === "string" && beat.scene.length > 0 ? beat.scene : path.join("scenes", `${(0, util_1.pascalCase)(id)}.tsx`);
+        const file = path.resolve(videoDir, rel);
+        if (file !== videoDir && !file.startsWith(videoDir + path.sep))
+            return null;
+        try {
+            return fs.readFileSync(file, "utf8");
+        }
+        catch {
+            return null;
+        }
+    };
+    return checkScriptLogic(beatsJson, card, readScene);
+}
+function registerCheckScript(server) {
+    server.registerTool("check_script", {
+        title: "Lint a lesson script against its concept card",
+        description: "Mechanical lint for a Supernova lesson script, no model call: it counts and matches patterns, so it can " +
+            "say a sentence is long or a term was never defined, not that the explanation is good. Reads " +
+            "src/videos/<videoName>/beats.json and concept.json ({ goal, terms: string[], example, reference?, referenceSpoken?, maxSeconds? }, next to it), or the " +
+            "beatsJson and conceptCard inputs. Returns { ok, beatsChecked, findings } where each finding has a severity " +
+            "(error, warning or note), the check, and the beat it points at. Checks: average sentence length per beat " +
+            "(warning above 16 words), Flesch-Kincaid reading level per beat (warning above grade 9), each concept-card " +
+            "term used with a definition beside it at first mention (note), more than two new terms in a beat (warning), " +
+            "every Equation's `spoken` string present in its beat's narration (error; the scene is read from the beat's " +
+            "scene path or scenes/<BeatId>.tsx), a hook in the first sentence that is a question or holds a number and " +
+            "does not open \"in this video\" (error for that opener, warning otherwise), words per second against the " +
+            "beat length using validate_beats' own budget (error), a last beat that ends with a question (error), the " +
+            "total length against the card's maxSeconds (default 120, error), and, when the card has a reference such as a " +
+            "chapter code, that the first beat's narration says its referenceSpoken (error; warning if referenceSpoken is missing). " +
+            "ok is false only when a finding is an error. See SCRIPT.md's lesson script rules.",
+        inputSchema: {
+            projectRoot: zod_1.z.string().optional(),
+            videoName: zod_1.z.string().min(1),
+            beatsJson: zod_1.z.unknown().optional().describe("The beats file as an object, instead of reading beats.json."),
+            conceptCard: zod_1.z
+                .object({
+                goal: zod_1.z.string(),
+                terms: zod_1.z.array(zod_1.z.string()),
+                example: zod_1.z.string(),
+                reference: zod_1.z.string().optional(),
+                referenceSpoken: zod_1.z.string().optional(),
+                maxSeconds: zod_1.z.number().positive().optional(),
+            })
+                .optional()
+                .describe("The concept card, instead of reading concept.json."),
+        },
+    }, async (input) => (0, mcp_1.runTool)("check_script", () => runCheckScript(input)));
+}

package/dist/tools/collectFacts.d.ts

@@ -0,0 +1,82 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type FactRecord } from "../facts";
+/**
+ * collect_facts: merges the run records tools wrote (see facts.ts) into one
+ * src/videos/<name>/facts.json for a video.
+ *
+ * It reports what ran, then sets that against what beats.json claims. A beat that claims a
+ * real capture with no capture record behind it, or a capture whose file has since vanished,
+ * shows up under `discrepancies`. It does not decide whether a discrepancy matters; that is
+ * the reader's call.
+ */
+export interface CollectFactsInput {
+    projectRoot?: string;
+    videoName: string;
+}
+interface BeatLike {
+    id: string;
+    start?: number;
+    duration?: number;
+    visual?: {
+        captureMethod?: string;
+        source?: string;
+    };
+}
+export interface BeatFacts {
+    /** What beats.json says this beat's picture is. */
+    claimed: {
+        captureMethod: string | null;
+        source: string | null;
+    };
+    /** "capture" if a capture tool ran for it, "construction" if the beat claims no capture. */
+    provenance: "capture" | "construction" | "unverified";
+    /** The latest record per capture tool for this beat. */
+    captures: Record<string, unknown>[];
+    render: {
+        status: "rendered" | "reused" | "unknown";
+        recordedAt: string;
+    } | null;
+    validation: {
+        tool: string;
+        recordedAt: string;
+        findings: Record<string, unknown>[];
+    }[];
+}
+export interface FactsDocument {
+    schemaVersion: number;
+    videoName: string;
+    collectedAt: string;
+    recordsRead: number;
+    recordsUsed: number;
+    beats: Record<string, BeatFacts>;
+    video: {
+        composition: Record<string, unknown> | null;
+        render: Record<string, unknown> | null;
+        /** The last finalize_video run: the measured loudness, the poster beat, the share copy. */
+        final: Record<string, unknown> | null;
+        validation: Record<string, unknown>;
+    };
+    discrepancies: {
+        beatId: string;
+        kind: string;
+        detail: string;
+    }[];
+}
+export interface CollectFactsResult {
+    factsPath: string;
+    recordsRead: number;
+    recordsUsed: number;
+    beatsWithCapture: string[];
+    discrepancies: FactsDocument["discrepancies"];
+}
+/** Pure: builds the document from records and a beats list. File checks go through `fileExists`. */
+export declare function buildFactsDocument(opts: {
+    videoName: string;
+    beats: BeatLike[];
+    records: FactRecord[];
+    fileExists: (relPath: string) => boolean;
+    now?: Date;
+}): FactsDocument;
+export declare function runCollectFacts(input: CollectFactsInput): CollectFactsResult;
+export declare function registerCollectFacts(server: McpServer): void;
+export {};