@openvidstudio/mcp-server 0.1.0 → 1.4.0

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,105 @@
+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;
+    /**
+     * The lesson's shape. "seven-beat" (the default, and what a card without this field gets) is the arc in SCRIPT.md;
+     * "story" is the story-first arc: a real situation told as a problem, a narrator, the key formulas, the formulas
+     * applied to the story's numbers, one watch out, then a practice question. The story fields below are only read
+     * for "story".
+     */
+    arc?: "seven-beat" | "story";
+    /** Story arc: the one real-world scene the lesson opens on. The first beat has to name it. */
+    situation?: string;
+    /** Story arc: the narrator's name. */
+    character?: string;
+    /**
+     * Story arc: the key formulas, in the order they are stated. `tex` is what is on screen, `spoken` how it is said
+     * (it has to occur in the narration, in this order), `source` where it comes from (a syllabus booklet, a derivation).
+     */
+    formulas?: StoryFormula[];
+    /** Story arc: the original practice question. The last beat ends with it. */
+    practiceQuestion?: string;
+    /** Story arc: the practice question's answer. It is withheld from the narration (it goes in the pinned comment). */
+    answer?: string;
+}
+export interface StoryFormula {
+    tex: string;
+    spoken: string;
+    source: string;
+}
+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" | "story-situation" | "story-formula" | "story-practice" | "story-comment" | "story-subscribe" | "story-answer";
+    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[];
+/**
+ * The `spoken` strings of each `<Derivation>` in a scene's source, in step order, one list per Derivation. The steps
+ * may be written inline (`steps={[{ tex, spoken }, ...]}`) or as a constant in the same file (`steps={STEPS}`).
+ */
+export declare function derivationSpoken(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 {};