@openvidstudio/mcp-server 0.1.0 → 1.3.1

package/dist/tools/releaseDiff.js

@@ -0,0 +1,319 @@
+"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.routeSlug = routeSlug;
+exports.routesFromDiff = routesFromDiff;
+exports.buildDraftManifest = buildDraftManifest;
+exports.runReleaseDiff = runReleaseDiff;
+exports.registerReleaseDiff = registerReleaseDiff;
+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 frameDiff_1 = require("../frameDiff");
+const planShots_1 = require("./planShots");
+const mcp_1 = require("./mcp");
+const REF = /^[A-Za-z0-9._\-/]{1,200}$/;
+function sanitizeRef(ref) {
+    if (!REF.test(ref) || ref.includes("..")) {
+        throw new Error(`"${ref}" is not a usable git ref. Use a branch, tag, or commit sha.`);
+    }
+    return ref;
+}
+/** Turns a route into a beat id and a file name. */
+function routeSlug(route) {
+    const slug = route.replace(/^\//, "").replace(/[^A-Za-z0-9]+/g, "-").replace(/^-|-$/g, "");
+    return slug.length > 0 ? slug : "home";
+}
+/**
+ * Which routes a diff between two refs could plausibly have changed.
+ *
+ * Deliberately generous. A changed component under src/components has no route of its own
+ * but can repaint every page, so when anything outside the route tree changes, every route
+ * becomes a candidate. The visual comparison is what narrows it back down, and it is a far
+ * more reliable filter than guessing at an import graph.
+ */
+function routesFromDiff(changedFiles, allRoutes) {
+    const changedRoutes = (0, planShots_1.discoverRoutes)(changedFiles);
+    const touchedShared = changedFiles.some((f) => !/(?:^|\/)(?:src\/)?(?:app|pages)\//.test(f.replace(/\\/g, "/")) && /\.(tsx|jsx|ts|js|css|scss)$/.test(f));
+    if (touchedShared)
+        return allRoutes;
+    return changedRoutes.length > 0 ? changedRoutes : [];
+}
+function listFiles(root, max = 4000) {
+    const out = [];
+    const skip = new Set(["node_modules", ".git", "dist", "build", ".next", "out", "coverage"]);
+    const walk = (dir) => {
+        if (out.length >= max)
+            return;
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (out.length >= max)
+                return;
+            if (entry.name.startsWith("."))
+                continue;
+            if (skip.has(entry.name))
+                continue;
+            const full = path.join(dir, entry.name);
+            if (entry.isDirectory())
+                walk(full);
+            else
+                out.push(path.relative(root, full));
+        }
+    };
+    walk(root);
+    return out;
+}
+/**
+ * The draft manifest: a before/after pair per changed route.
+ *
+ * Both sides are `existing-asset` beats, because that is what they honestly are. The
+ * "before" frame cannot be re-captured from a live URL once the release is out, and the
+ * "after" frame was captured at a specific ref rather than from whatever is running now.
+ * Attribution on each says which ref it came from, which is the point of that field.
+ *
+ * `vo` is left empty on purpose. Writing the narration is drafting content, this server
+ * does not draft content, and PLANNING.md's approval gate exists precisely so a human sees
+ * the words before they are spoken over their product. The suggested word count is included
+ * so whoever writes them knows what fits.
+ */
+function buildDraftManifest(opts) {
+    const { beforeRef, afterRef, changes, fps, beatFrames } = opts;
+    const seconds = beatFrames / fps;
+    const beats = [];
+    let start = 0;
+    for (const change of changes) {
+        const slug = routeSlug(change.route);
+        for (const [side, ref, assetPath] of [
+            ["before", beforeRef, change.beforePath],
+            ["after", afterRef, change.afterPath],
+        ]) {
+            beats.push({
+                id: `${slug}-${side}`,
+                start,
+                duration: beatFrames,
+                vo: "",
+                visual: {
+                    captureMethod: "existing-asset",
+                    assetPath,
+                    attribution: `${change.route} captured from ${ref}`,
+                    caption: `${change.route} ${side === "before" ? "before" : "after"} ${ref}`,
+                },
+            });
+            start += beatFrames;
+        }
+    }
+    return {
+        fps,
+        title: `What changed between ${beforeRef} and ${afterRef}`,
+        // Anything reading this file should know it is not finished.
+        draft: true,
+        suggestedWordsPerBeat: Math.round(seconds * 2.6),
+        beats,
+    };
+}
+async function runReleaseDiff(input) {
+    const videoName = (0, util_1.sanitizeSegment)(input.videoName, "videoName");
+    const projectRoot = (0, util_1.resolveProjectRoot)(input.projectRoot);
+    const repoRoot = path.resolve(input.repoRoot);
+    const beforeRef = sanitizeRef(input.beforeRef);
+    const afterRef = sanitizeRef(input.afterRef);
+    if (!fs.existsSync(repoRoot))
+        throw new Error(`${repoRoot} does not exist.`);
+    const allRoutes = (0, planShots_1.discoverRoutes)(listFiles(repoRoot));
+    let routes = input.routes?.length ? input.routes : [];
+    if (routes.length === 0) {
+        const diff = await (0, util_1.spawnCapture)("git", ["diff", "--name-only", `${beforeRef}..${afterRef}`], repoRoot);
+        if (diff.code !== 0) {
+            throw new Error(`git could not diff ${beforeRef}..${afterRef} in ${repoRoot}:\n${diff.stderr.slice(-600)}\n` +
+                `Pass an explicit routes list to skip detection.`);
+        }
+        routes = routesFromDiff(diff.stdout.split(/\r?\n/).filter(Boolean), allRoutes);
+    }
+    if (routes.length === 0) {
+        throw new Error(`Nothing between ${beforeRef} and ${afterRef} touches a route, so there is no UI change to film. ` +
+            `That is a real answer: not every release has a visual story. Pass an explicit routes list to ` +
+            `check anyway.`);
+    }
+    const outRel = path.join("public", "images", "release", videoName);
+    const outAbs = path.join(projectRoot, outRel);
+    fs.mkdirSync(path.join(outAbs, "before"), { recursive: true });
+    fs.mkdirSync(path.join(outAbs, "after"), { recursive: true });
+    const target = input.viewport ?? capture_1.DEFAULT_VIEWPORT;
+    const deviceScaleFactor = input.deviceScaleFactor ?? capture_1.DEFAULT_DEVICE_SCALE;
+    const changes = [];
+    const browser = await (0, capture_1.launchChromium)();
+    try {
+        for (const route of routes) {
+            const slug = routeSlug(route);
+            const shots = { before: "", after: "" };
+            for (const [side, baseUrl] of [
+                ["before", input.beforeUrl],
+                ["after", input.afterUrl],
+            ]) {
+                const rel = path.join(outRel, side, `${slug}.png`);
+                const url = new URL(route, baseUrl).toString();
+                // deviceScaleFactor set at context creation, matching capture_screenshot's own
+                // convention, so these captures are on equal footing with every other asset this
+                // pipeline produces (and so a future docs_drift binding against one of them has a
+                // real sidecar to read instead of guessing from the PNG's pixel size).
+                const context = await browser.newContext({ deviceScaleFactor });
+                try {
+                    const page = await context.newPage();
+                    try {
+                        await page.setViewportSize(target);
+                        await page.goto(url, { waitUntil: "networkidle" });
+                        // Same compensation the normal capture path uses. Without it the two sides can
+                        // be captured at different effective viewports and every route reads as changed.
+                        const { zoom } = await (0, capture_1.detectAndCompensateZoom)(page, target);
+                        await (0, capture_1.replayInteractions)(page, input.interactions);
+                        const outPathAbs = path.join(projectRoot, rel);
+                        await page.screenshot({ path: outPathAbs, scale: "device" });
+                        (0, capture_1.writeCaptureSidecar)(outPathAbs, {
+                            url,
+                            viewport: target,
+                            deviceScaleFactor,
+                            zoom,
+                            ...(input.interactions?.length ? { interactions: input.interactions } : {}),
+                            capturedAt: new Date().toISOString(),
+                        });
+                        shots[side] = rel;
+                    }
+                    finally {
+                        await page.close();
+                    }
+                }
+                finally {
+                    await context.close();
+                }
+            }
+            const diffRel = path.join(outRel, `${slug}.diff.png`);
+            const comparison = await (0, frameDiff_1.compareFrames)(path.join(projectRoot, shots.before), path.join(projectRoot, shots.after), { diffPath: path.join(projectRoot, diffRel) });
+            const verdict = (0, frameDiff_1.judgeDrift)(comparison, {
+                changedRatio: input.changedRatioThreshold,
+                meanDelta: input.meanDeltaThreshold,
+            });
+            changes.push({
+                route,
+                changed: verdict.drifted,
+                reason: verdict.reason,
+                changedRatio: comparison.changedRatio,
+                meanDelta: comparison.meanDelta,
+                beforePath: shots.before,
+                afterPath: shots.after,
+                diffPath: diffRel,
+            });
+        }
+    }
+    finally {
+        await browser.close();
+    }
+    const changed = changes.filter((c) => c.changed);
+    const draftRel = path.join("output", "release", videoName, "beats.draft.json");
+    const draftAbs = path.join(projectRoot, draftRel);
+    fs.mkdirSync(path.dirname(draftAbs), { recursive: true });
+    fs.writeFileSync(draftAbs, JSON.stringify(buildDraftManifest({ videoName, beforeRef, afterRef, changes: changed, fps: 30, beatFrames: 90 }), null, 2) + "\n", "utf8");
+    const nextSteps = changed.length === 0
+        ? [
+            `None of the ${changes.length} routes checked actually changed on screen between ${beforeRef} and ` +
+                `${afterRef}. This release has no visual story, which is a real answer: a what's-new clip showing ` +
+                `four identical pages is worse than no clip.`,
+        ]
+        : [
+            `${changed.length} of ${changes.length} routes changed: ${changed.map((c) => c.route).join(", ")}.`,
+            `The draft manifest at ${draftRel} has a before/after pair per route, with every "vo" left empty.`,
+            `Write the narration (roughly ${Math.round((90 / 30) * 2.6)} words per beat at this duration), show ` +
+                `the full draft to the dev for approval, then write_beats_file. This tool does not draft the ` +
+                `script and does not install the manifest.`,
+            `Then scaffold_scene each beat, stitch_composition, and render_video with incremental: true.`,
+        ];
+    return {
+        beforeRef,
+        afterRef,
+        routesConsidered: routes,
+        changedRoutes: changed.map((c) => c.route),
+        routes: changes,
+        draftPath: draftRel,
+        nextSteps,
+    };
+}
+function registerReleaseDiff(server) {
+    server.registerTool("release_diff", {
+        title: "Two refs in, a what's-new clip's manifest out",
+        description: "Works out which UI surfaces changed between two releases, captures each on both sides, drops the " +
+            "ones that did not actually change on screen, and drafts a before/after manifest for a what's-new " +
+            "clip. This is the change that turns one demo video per project into one per release. The filtering " +
+            "is the important half: a release is mostly dependency bumps and refactors, and a clip showing four " +
+            "identical pages is worse than no clip, so every candidate route is compared and the numbers are " +
+            "reported. Route detection uses git: a changed file under app/ or pages/ names its own route, and a " +
+            "change anywhere else in the source makes every route a candidate, since a shared component can " +
+            "repaint all of them. It needs a running instance per ref (a preview deployment and production are " +
+            "exactly this pair, and so are two local ports): it will not check out, build, and serve an " +
+            "arbitrary project, because doing that safely for any stack is not something a video tool should " +
+            "claim. The draft is written to output/release/<videoName>/beats.draft.json and is deliberately not " +
+            "installed as the video's beats.json, with every `vo` left empty: writing narration is drafting " +
+            "content, and the approval gate exists so a human sees the words before they are spoken over their " +
+            "product. Each captured image gets the same `<path>.capture.json` sidecar capture_screenshot writes " +
+            "(url, viewport, deviceScaleFactor, zoom, interactions, capturedAt), so a docs_drift binding against " +
+            "one of these later has a real capture record to re-derive the viewport from instead of guessing one " +
+            "from the PNG's pixel size.",
+        inputSchema: {
+            projectRoot: zod_1.z.string().optional(),
+            videoName: zod_1.z.string().min(1),
+            repoRoot: zod_1.z.string().min(1).describe("The product repository, used only for route detection."),
+            beforeRef: zod_1.z.string().min(1),
+            afterRef: zod_1.z.string().min(1),
+            beforeUrl: zod_1.z.string().url().describe("A running instance of beforeRef."),
+            afterUrl: zod_1.z.string().url().describe("A running instance of afterRef."),
+            routes: zod_1.z.array(zod_1.z.string()).optional().describe("Skip detection and check exactly these."),
+            interactions: zod_1.z.array(capture_1.interactionSchema).optional(),
+            viewport: capture_1.viewportSchema.optional(),
+            deviceScaleFactor: zod_1.z
+                .number()
+                .positive()
+                .optional()
+                .describe("Pixels captured per CSS pixel. Defaults to 2, matching capture_screenshot's own default."),
+            changedRatioThreshold: zod_1.z.number().positive().optional(),
+            meanDeltaThreshold: zod_1.z.number().positive().optional(),
+        },
+    }, async (input) => (0, mcp_1.runTool)("release_diff", () => runReleaseDiff(input)));
+}

package/dist/tools/renderStills.d.ts

@@ -0,0 +1,138 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { SceneFinding } from "./validateScenes";
+export interface RenderStillsInput {
+    projectRoot?: string;
+    videoName: string;
+    /** Omit for every beat in this video's composition. */
+    beatIds?: string[];
+    /**
+     * Which frame within each beat to render. "mid" (default) is that beat's own midpoint;
+     * "start"/"end" are the beat's first/last frame; a number is an explicit frame offset
+     * relative to the beat's own start (clamped into the beat's own duration).
+     */
+    at?: "start" | "mid" | "end" | number;
+    /**
+     * Render this many stills per beat, spread from start to end. 1 is the midpoint, 2 is start
+     * and end, 3 adds the middle, more are evenly spaced. "review" renders five per beat with the
+     * first and last pulled 3 frames inside the beat, so consecutive beats' stills show both
+     * sides of the cut between them. Overrides `at`.
+     */
+    perBeat?: number | "review";
+    /**
+     * Render exactly these frames, as global frame numbers against the whole composition, instead
+     * of sampling beats. Overrides `at`, `perBeat` and `beatIds`.
+     */
+    frames?: number[];
+    /** Overrides the composition id resolved from src/videos/.registry.json. */
+    compositionId?: string;
+    /** Overrides the default output/stills/<videoName>/ directory. */
+    outDir?: string;
+    /** Review round. Stills go to a round-<n> subfolder, so each round's grid is kept for comparison. */
+    round?: number | string;
+    /** Output resolution multiplier, same meaning as Remotion's own --scale. Defaults to 1. */
+    scale?: number;
+    /** Tile every still into one labelled contact-grid PNG. Defaults to true when there is more than one still. */
+    contactGrid?: boolean;
+    /**
+     * Also return validate_scenes's numeric render findings for the same beats (cropping, size,
+     * reading time, contrast, em dashes, safe area, HUD overlap, dead frames), so an agent that
+     * cannot view images can still review. Reuses this call's bundle. Defaults to true.
+     */
+    findings?: boolean;
+    /**
+     * A region of the composition, in composition pixels, to look at closely. Each still then
+     * gets a second file next to it, `<name>-crop.png`, the region re-rendered at a higher scale
+     * (about 960 px wide, at most 4x) rather than stretched from the 1x still, so small text can be
+     * checked for what it really looks like. The whole still is written as usual.
+     */
+    crop?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+}
+/** Pure: the render scale for a crop of this width. A whole number, since a fractional one cannot give whole-pixel dimensions. */
+export declare function cropScale(cropWidth: number): number;
+export interface RenderStillOutput {
+    beatId: string;
+    /** Global frame number against the whole stitched composition. */
+    frame: number;
+    /** Frame offset from the start of the beat. */
+    offset: number;
+    /** Human-readable position, for example "start+3" or "mid". Also the tile label in the contact grid. */
+    position: string;
+    path: string;
+    width: number;
+    height: number;
+    bytes: number;
+    /** Present when `crop` was requested: the region at a higher scale. */
+    crop?: {
+        path: string;
+        width: number;
+        height: number;
+        scale: number;
+    };
+}
+export interface ContactGridOutput {
+    path: string;
+    width: number;
+    height: number;
+    columns: number;
+    rows: number;
+    tiles: number;
+}
+export interface RenderStillsResult {
+    compositionId: string;
+    stills: RenderStillOutput[];
+    /** Present when more than one still was rendered, or contactGrid was true. */
+    contactGrid?: ContactGridOutput;
+    /** Numeric render findings for the rendered beats, unless findings was false. */
+    findings?: SceneFinding[];
+    /** Beats the numeric findings could not measure, and why. A skipped beat is never "clean". */
+    findingsSkipped?: {
+        beatId: string;
+        reason: string;
+    }[];
+    /** How long the one-time bundle step took. This is the cost render_stills amortizes. */
+    bundleMs: number;
+    /** How long rendering every requested still took, from the SAME bundle. */
+    renderMs: number;
+    totalMs: number;
+}
+interface BeatLike {
+    id: string;
+    start: number;
+    duration: number;
+}
+/** Pure, unit-testable: resolves which global frame a beat's representative still is at. */
+export declare function resolveBeatFrame(beat: BeatLike, at: RenderStillsInput["at"]): number;
+export interface PlannedStill {
+    beatId: string;
+    frame: number;
+    offset: number;
+    position: string;
+}
+/**
+ * Pure: which frames of a beat to render. Offsets are clamped into the beat and deduplicated,
+ * so a very short beat yields fewer stills rather than the same frame twice.
+ */
+export declare function planBeatStills(beat: BeatLike, perBeat: number | "review"): PlannedStill[];
+/** Pure: the beat a global frame belongs to, and its offset into it. Frames past the end clamp to the last beat. */
+export declare function locateFrame(beats: BeatLike[], frame: number): {
+    beat: BeatLike;
+    offset: number;
+};
+export declare function resolveCompositionId(projectRoot: string, videoName: string, override?: string): string;
+/**
+ * Tiles rendered stills into one labelled PNG. A beat's stills share a row when perBeat was
+ * used, so reading across is time within a beat and reading down is the cut from one beat to
+ * the next; otherwise tiles fill rows of up to four. Each tile carries its beat id and
+ * position in a band above its picture, drawn as SVG so no font file has to be installed.
+ */
+export declare function buildContactGrid(stills: Pick<RenderStillOutput, "beatId" | "path" | "position" | "offset" | "frame">[], outPath: string, opts?: {
+    columns?: number;
+}): Promise<ContactGridOutput>;
+export declare function runRenderStills(input: RenderStillsInput): Promise<RenderStillsResult>;
+export declare function registerRenderStills(server: McpServer): void;
+export {};