reelme 0.2.2 → 0.4.0

package/src/cli.mjs

@@ -4,30 +4,33 @@
 // skill owns the intelligence and writes reelme.json; this CLI never asks
 // questions.
 
-import { spawnSync } from "node:child_process";
-import { ensureScaffold, cleanCache, fail } from "./cache.mjs";
-import { render } from "./render.mjs";
+import { ensureScaffold, cleanCache, readBrief, runShell, fail } from "./cache.mjs";
+import { render, stageInputs } from "./render.mjs";
 
 const USAGE = `reelme — launch videos for your repo, rendered locally
 
 Usage: npx reelme <command>
 
 Commands:
-  render   Render every platform in reelme.json to ./reelme-out/
-  studio   Open Remotion Studio against the cached project (preview/tweak)
-  clean    Remove the reelme cache (~/.reelme/cache)
+  render       Render every platform in reelme.json to ./reelme-out/
+  studio       Open Remotion Studio against the cached project (preview/tweak)
+  validate     Check reelme.json (schema, platforms, scenes) without rendering
+  clean        Remove this project's reelme cache
+  clean --all  Remove every project's cache (~/.reelme/cache)
 
 The brief (reelme.json) lives at your repo root — create it with the
 /reelme agent skill: npx skills add RubenGlez/reelme
 `;
 
+// Studio runs the same staging pipeline as render (minus the render loop) so a
+// preview shows exactly what render() would produce — assets, audio, and logo
+// all staged, and a missing brief reported cleanly (F1).
 function studio(repoRoot) {
+  const brief = readBrief(repoRoot);
   const cacheDir = ensureScaffold(repoRoot);
+  stageInputs(repoRoot, cacheDir, brief);
   console.log("reelme: opening Remotion Studio (Ctrl+C to stop)…");
-  const result = spawnSync("pnpm", ["exec", "remotion", "studio"], {
-    cwd: cacheDir,
-    stdio: "inherit",
-  });
+  const result = runShell("pnpm", ["exec", "remotion", "studio"], cacheDir);
   if (result.error) fail(`failed to open Studio: ${result.error.message}`);
 }
 
@@ -41,8 +44,14 @@ switch (command) {
   case "studio":
     studio(repoRoot);
     break;
+  case "validate":
+    // readBrief validates schema, platforms, and every scene, exiting non-zero
+    // with named errors on failure. A cheap pre-render check for the skill.
+    readBrief(repoRoot);
+    console.log("reelme: reelme.json is valid.");
+    break;
   case "clean":
-    cleanCache();
+    cleanCache(repoRoot, process.argv.includes("--all"));
     break;
   case "--help":
   case "-h":

package/src/render.mjs

@@ -2,19 +2,172 @@
 // variant per social platform when the brief has a teaser cut. Outputs land
 // in <repo>/reelme-out/; the heavy Remotion project stays in the cache.
 
-import { cpSync, mkdirSync } from "node:fs";
-import { basename, join } from "node:path";
+import { cpSync, existsSync, mkdirSync, readFileSync, rmSync } from "node:fs";
+import { basename, dirname, join, resolve, relative, isAbsolute } from "node:path";
 import { spawnSync } from "node:child_process";
-import { ensureScaffold, loadPlatforms, readBrief, fail } from "./cache.mjs";
+import { createRequire } from "node:module";
+import { AUDIO_DIR, ensureScaffold, loadPlatforms, readBrief, runShell, fail } from "./cache.mjs";
+
+const require = createRequire(import.meta.url);
+
+// Reject asset paths that escape their base dir. A reelme.json is authored by an
+// agent and gets committed/shared, so a `../../…` src/logo would otherwise copy
+// (or read) files outside the cache at render time (F11). Guards both the repo
+// source and the cache destination.
+function safeJoin(baseDir, relPath, label) {
+  if (typeof relPath !== "string" || relPath.length === 0 || isAbsolute(relPath)) {
+    fail(`${label} "${relPath}" must be a repo-relative path.`);
+  }
+  const dest = resolve(baseDir, relPath);
+  const rel = relative(baseDir, dest);
+  if (rel.startsWith("..") || isAbsolute(rel)) {
+    fail(`${label} "${relPath}" escapes the project directory — refusing to copy.`);
+  }
+  return dest;
+}
+
+// Resolve the gifsicle binary: prefer the optionalDependency's bundled build,
+// fall back to a system install on PATH. Returns null when neither is present.
+function gifsicleBin() {
+  try {
+    const mod = require("gifsicle");
+    // The package exports the binary path; under Node's require-ESM it arrives
+    // as a namespace ({ default: path }) rather than a bare string.
+    const p = typeof mod === "string" ? mod : mod?.default;
+    if (typeof p === "string" && existsSync(p)) return p;
+  } catch {
+    // optionalDependency not installed — fall through to a PATH lookup.
+  }
+  return "gifsicle";
+}
+
+// Lossy gif pass. Remotion's native gif is already well quantized, but a
+// gifsicle --lossy run roughly halves it again with text left crisp. Our
+// atmosphere gradients band under palette/colour reduction, so we keep the full
+// palette and only apply --lossy. Best-effort: a missing gifsicle is non-fatal.
+function optimizeGif(file) {
+  const res = spawnSync(gifsicleBin(), ["-b", "-O3", "--lossy=60", file], { stdio: "ignore" });
+  if (res.error || res.status !== 0) {
+    console.warn("reelme: note — gif left unoptimized (install gifsicle for ~50% smaller files).");
+  }
+}
 
 function renderComposition(cacheDir, compositionId, outFile, codec) {
   const args = ["exec", "remotion", "render", compositionId, join("out", outFile)];
-  if (codec === "gif") args.push("--codec=gif");
+  // Render gifs at 0.6 scale (e.g. 1920x1080 -> 1152x648): a README gif needs no
+  // more, and fewer pixels roughly halves the file size. Layout and timing are
+  // unchanged — --scale downscales the output, not the composition coordinates.
+  if (codec === "gif") {
+    args.push("--codec=gif", "--scale=0.6");
+  } else {
+    // Remotion's default h264 bitrate is far higher than a social upload needs;
+    // crf 20 is visually lossless and cuts the file to roughly a third.
+    args.push("--crf=20");
+  }
   console.log(`reelme: rendering ${compositionId} → reelme-out/${outFile}`);
-  const result = spawnSync("pnpm", args, { cwd: cacheDir, stdio: "inherit" });
+  const result = runShell("pnpm", args, cacheDir);
   if (result.error || result.status !== 0) {
     fail(`render failed for platform composition "${compositionId}".`);
   }
+  if (codec === "gif") optimizeGif(join(cacheDir, "out", outFile));
+}
+
+function collectAssets(brief) {
+  const assets = [];
+  const cuts = [brief.cuts.main, brief.cuts.vertical, brief.cuts.teaser].filter(Boolean);
+  for (const cut of cuts) {
+    for (const scene of cut) {
+      if (scene.type === "clip" && scene.src) assets.push(scene.src);
+      if (scene.type === "mobile" && scene.screenshot) assets.push(scene.screenshot);
+      if (scene.type === "browser" && scene.image) assets.push(scene.image);
+    }
+  }
+  return [...new Set(assets)];
+}
+
+function copyAssets(repoRoot, cacheDir, brief) {
+  const assets = collectAssets(brief);
+  if (assets.length === 0) return;
+  const publicDir = join(cacheDir, "public");
+  mkdirSync(publicDir, { recursive: true });
+  // Resolve every path through the traversal guard before touching the disk.
+  const resolved = assets.map((asset) => ({
+    asset,
+    source: safeJoin(repoRoot, asset, "asset"),
+    dest: safeJoin(publicDir, asset, "asset"),
+  }));
+  const missing = resolved.filter(({ source }) => !existsSync(source));
+  if (missing.length > 0) {
+    fail(`missing asset file(s):\n${missing.map(({ source }) => `  ${source}`).join("\n")}`);
+  }
+  for (const { source, dest } of resolved) {
+    mkdirSync(dirname(dest), { recursive: true });
+    cpSync(source, dest);
+  }
+}
+
+function loadAudioManifest() {
+  const manifestPath = join(AUDIO_DIR, "manifest.json");
+  if (!existsSync(manifestPath)) {
+    fail(`audio manifest is missing from the package: ${manifestPath}`);
+  }
+  try {
+    const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+    if (!Array.isArray(manifest)) throw new Error("manifest must be an array");
+    return manifest;
+  } catch (e) {
+    fail(`audio manifest is invalid: ${e.message}`);
+  }
+}
+
+function copyAudioTrack(cacheDir, brief) {
+  const audio = brief.project?.audio;
+  if (!audio) return;
+
+  const track = audio.track;
+  if (typeof track !== "string" || track.length === 0 || basename(track) !== track) {
+    fail(`project.audio.track must be a filename from the bundled audio manifest.`);
+  }
+
+  const manifest = loadAudioManifest();
+  const validTracks = manifest.map((entry) => entry.file).filter(Boolean);
+  const entry = manifest.find((item) => item.file === track);
+  if (!entry) {
+    fail(
+      `unknown audio track "${track}". Valid tracks: ${validTracks.join(", ")}.`
+    );
+  }
+
+  const source = join(AUDIO_DIR, track);
+  if (!existsSync(source)) {
+    fail(`bundled audio track "${track}" is missing from ${AUDIO_DIR}.`);
+  }
+
+  const audioDir = join(cacheDir, "public", "audio");
+  mkdirSync(audioDir, { recursive: true });
+  cpSync(source, join(audioDir, track));
+}
+
+function copyLogo(repoRoot, cacheDir, brief) {
+  const logo = brief.project?.logo;
+  if (!logo) return;
+  const source = safeJoin(repoRoot, logo, "project.logo");
+  if (!existsSync(source)) {
+    fail(`project.logo file not found: ${source}`);
+  }
+  const publicDir = join(cacheDir, "public");
+  const dest = safeJoin(publicDir, logo, "project.logo");
+  mkdirSync(dirname(dest), { recursive: true });
+  cpSync(source, dest);
+}
+
+// Stage every render input into the cache. Shared by render() and studio() so
+// Studio previews exactly what render() produces (F1) instead of showing 404s
+// for missing assets/audio/logo.
+export function stageInputs(repoRoot, cacheDir, brief) {
+  copyAssets(repoRoot, cacheDir, brief);
+  copyAudioTrack(cacheDir, brief);
+  copyLogo(repoRoot, cacheDir, brief);
 }
 
 export function render(repoRoot) {
@@ -24,13 +177,15 @@ export function render(repoRoot) {
   const outDir = join(repoRoot, "reelme-out");
   mkdirSync(outDir, { recursive: true });
 
+  stageInputs(repoRoot, cacheDir, brief);
+
   const verticalFallback = brief.project.platforms.filter(
     (id) => platforms[id].cut === "vertical" && !brief.cuts.vertical?.length
   );
   if (verticalFallback.length > 0) {
     console.warn(
-      `reelme: warning — no cuts.vertical in reelme.json; ${verticalFallback.join(", ")} will render ` +
-        `the main cut letterboxed into 9:16. Author a vertical cut for better results.`
+      `reelme: warning — no cuts.vertical in reelme.json; ${verticalFallback.join(", ")} will re-render ` +
+        `the main cut at 9:16. Dense wide scenes may cramp — author a vertical cut for better results.`
     );
   }
 
@@ -38,7 +193,7 @@ export function render(repoRoot) {
     const preset = platforms[id];
     const outFile = basename(preset.output.file);
     renderComposition(cacheDir, `Reel-${id}`, outFile, preset.output.codec);
-    cpSync(join(cacheDir, "out", outFile), join(outDir, outFile));
+    copyOut(cacheDir, outFile, outDir);
   }
 
   const hasTeaser = Array.isArray(brief.cuts.teaser) && brief.cuts.teaser.length > 0;
@@ -49,9 +204,17 @@ export function render(repoRoot) {
     for (const id of socialIds) {
       const outFile = `${id}-teaser.mp4`;
       renderComposition(cacheDir, `Reel-${id}-teaser`, outFile, "h264");
-      cpSync(join(cacheDir, "out", outFile), join(outDir, outFile));
+      copyOut(cacheDir, outFile, outDir);
     }
   }
 
   console.log(`reelme: done — outputs in ${outDir}`);
 }
+
+// Copy a finished render to reelme-out/, then drop the cache copy so out/ doesn't
+// accumulate every render forever (F16). The deliverable already lives in the repo.
+function copyOut(cacheDir, outFile, outDir) {
+  const cached = join(cacheDir, "out", outFile);
+  cpSync(cached, join(outDir, outFile));
+  rmSync(cached, { force: true });
+}

package/template/package.json

@@ -9,11 +9,14 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@remotion/cli": "4.0.290",
-    "@remotion/google-fonts": "4.0.290",
+    "@remotion/cli": "4.0.410",
+    "@remotion/gif": "4.0.410",
+    "@remotion/google-fonts": "4.0.410",
     "chroma-js": "^3.1.2",
     "lucide-react": "^0.511.0",
-    "remotion": "4.0.290"
+    "react": "^18.3.0",
+    "react-dom": "^18.3.0",
+    "remotion": "4.0.410"
   },
   "devDependencies": {
     "@types/chroma-js": "^2.4.4",
@@ -21,8 +24,6 @@
     "@typescript-eslint/eslint-plugin": "^8.0.0",
     "@typescript-eslint/parser": "^8.0.0",
     "eslint": "^9.0.0",
-    "react": "^18.3.0",
-    "react-dom": "^18.3.0",
     "typescript": "^5.4.0",
     "vite": "^7.3.5",
     "vitest": "^4.1.8"