belt-trailer 0.1.0

data/lib/belt/commands/trailer_command.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+require_relative '../trailer'
+
+module Belt
+  module Commands
+    # `belt trailer film|cut|check` — runs the trailer engine on a frontend.
+    class TrailerCommand
+      SUBCOMMANDS = %w[film cut check].freeze
+
+      def self.description
+        'Film, cut and check a launch trailer from the app itself (belt-trailer)'
+      end
+
+      def self.run(args)
+        new.run(args.dup)
+      end
+
+      def run(args)
+        command = args.shift
+        return help if command.nil? || %w[help --help -h].include?(command)
+        return guide if command == 'guide'
+
+        unless SUBCOMMANDS.include?(command)
+          warn "Unknown command: belt trailer #{command}. Run `belt trailer help`."
+          exit 1
+        end
+        return help if args.include?('--help') || args.include?('-h')
+
+        app_dir = frontend_dir(extract_flag!(args, '--frontend'))
+        config = option(args, '--config') || Belt::Trailer::CONFIG_FILE
+        missing = Belt::Trailer.missing_requirements(app_dir, config: config)
+        unless missing.empty?
+          warn "belt trailer needs:\n#{missing.map { |m| "  - #{m}" }.join("\n")}"
+          exit 1
+        end
+
+        exit(system(*Belt::Trailer.engine_command(command, app_dir, args)) ? 0 : 1)
+      end
+
+      # The frontend's directory: --frontend NAME from config/frontends.yml,
+      # else the default one, else frontend/.
+      def frontend_dir(name)
+        registry = registry_class&.load
+        return 'frontend' if registry.nil? || (registry.empty? && name.nil?)
+
+        registry.resolve!(name).path
+      end
+
+      private
+
+      def registry_class
+        require 'belt/cli/frontend_registry'
+        Belt::CLI::FrontendRegistry
+      rescue LoadError
+        nil
+      end
+
+      def extract_flag!(args, flag)
+        index = args.index { |a| a == flag || a.start_with?("#{flag}=") }
+        return nil unless index
+
+        arg = args.delete_at(index)
+        arg.include?('=') ? arg.split('=', 2).last : args.delete_at(index)
+      end
+
+      def option(args, flag)
+        index = args.index { |a| a == flag || a.start_with?("#{flag}=") }
+        return nil unless index
+
+        args[index].include?('=') ? args[index].split('=', 2).last : args[index + 1]
+      end
+
+      # The skill for agents making a trailer, with its references' full paths.
+      def guide
+        skill = File.join(Belt::Trailer::SKILL_DIR, 'SKILL.md')
+        puts "# #{skill}\n\n"
+        puts File.read(skill).gsub('](references/', "](#{Belt::Trailer::SKILL_DIR}/references/")
+                 .gsub('<gem>', Belt::Trailer::ROOT)
+      end
+
+      def help
+        puts <<~HELP
+          Film a launch trailer of the app from its own screens and sounds.
+
+          Usage: belt trailer <film|cut|check|guide> [options]
+
+            film    Film each beat of the storyboard in trailer.config.mjs:
+                    <beat>-<format>.mp4, <beat>-<format>-clean.mp4 (no titles)
+                    and <beat>-<format>.json (the sounds it played, its marks)
+            cut     Join the beats in order with their sounds and the music,
+                    levelled to -14 LUFS: trailer-<format>.mp4
+            check   Pass or fail the cut: audio from 0 for the whole video,
+                    -14 LUFS ±1, true peak below -1 dBFS, at most 30 s, every
+                    effect on its frame, no title in the last 0.5 s of a beat.
+                    Writes trailer-<format>-sheet.png, a contact sheet to look at.
+            guide   The skill for agents making a trailer: storyboard, fixtures,
+                    beats, reviewing frames (start here)
+
+          Options:
+            --frontend NAME      Which frontend (config/frontends.yml; default: frontend/)
+            --only a,b           film: just these beats, by the names in the config
+            --format NAME        wide, tall or both (default)
+            --clean              film: delete those beats' old clips, leftover frames
+                                 and cached live sounds first
+            --keep-frames        film: keep the frame images
+            --music PLAN         cut, check: a named plan from music.plans
+            --sounds bundled     film, cut: the app's bundled sounds, not the live site's
+            --out DIR            Output directory (default: <frontend>/tmp/trailer)
+            --config FILE        Config file in the frontend (default: trailer.config.mjs)
+
+          Needs Node, ffmpeg and Playwright's Chromium in the frontend.
+          Start with `belt generate trailer`.
+
+          Examples:
+            belt trailer film --format wide
+            belt trailer film --only dragon --format wide
+            belt trailer cut && belt trailer check
+        HELP
+      end
+    end
+  end
+end

data/lib/belt/generators/trailer_generator.rb

@@ -0,0 +1,215 @@
+# frozen_string_literal: true
+
+require 'erb'
+require 'fileutils'
+require 'json'
+require_relative '../trailer'
+require_relative '../commands/trailer_command'
+
+module Belt
+  module Generators
+    # `belt generate trailer` — a starter trailer for a React + Vite frontend:
+    # trailer.config.mjs with a two-beat storyboard, a titles theme, and a
+    # minimal showcase (the app rendered from fixtures, no backend) if the
+    # frontend has none.
+    class TrailerGenerator
+      TEMPLATE_DIR = File.expand_path('../trailer/templates', __dir__)
+      # Showcases the generator recognises, its own first.
+      SHOWCASES = %w[scripts/showcase/build.mjs scripts/screenshots/build.mjs].freeze
+      SHOWCASE_FILES = %w[build.mjs showcase.html showcase.jsx fixtures.js].freeze
+      STARTER_BEATS = %w[hook end].freeze
+      AGENTS_MARKER = '## Launch trailer (belt-trailer)'
+      AGENTS_SECTION = <<~MD.freeze
+        #{AGENTS_MARKER}
+
+        The trailer is filmed from the app by belt-trailer. Before working on it,
+        read the skill: `belt trailer guide`. Storyboard first
+        (`FRONTEND/trailer-storyboard.md`), then fixtures, then the beats in
+        `FRONTEND/trailer.config.mjs`. Review every beat from its frames before
+        calling it done, and leave publishing (and music rights) to a person.
+      MD
+
+      def self.description
+        'Scaffold a launch trailer: trailer.config.mjs, a titles theme and a showcase'
+      end
+
+      def self.run(args)
+        return print_help if args.include?('--help') || args.include?('-h')
+
+        new(args).generate
+      end
+
+      def self.destroy(args)
+        new(args).destroy
+      end
+
+      def self.print_help
+        puts <<~HELP
+          Scaffold a launch trailer for a React + Vite frontend.
+
+          Usage: belt generate trailer [options]
+
+          Options:
+            --frontend NAME    Which frontend (config/frontends.yml; default: frontend/)
+            --url ADDRESS      The address on the end card (default: example.com)
+            --skip-showcase    Don't write a showcase, even if the frontend has none
+            --force            Overwrite existing files
+
+          What gets created (in the frontend):
+            trailer.config.mjs             The storyboard: beats, titles, music, canned API
+            trailer-titles.css             The titles' fonts and colours
+            trailer-storyboard.md          The storyboard to write first
+            scripts/showcase/              If there's no showcase yet: build.mjs,
+                                           showcase.html, showcase.jsx, fixtures.js
+
+          Then:
+            cd frontend && npm install -D playwright && npx playwright install chromium
+            belt trailer film --format wide
+            belt trailer cut && belt trailer check
+
+          Examples:
+            belt g trailer
+            belt g trailer --url myapp.com
+            belt d trailer
+        HELP
+      end
+
+      def initialize(args, out: $stdout)
+        args = args.dup
+        @out = out
+        @force = args.delete('--force')
+        @skip_showcase = args.delete('--skip-showcase')
+        @url = option(args, '--url') || 'example.com'
+        @dir = Belt::Commands::TrailerCommand.new.frontend_dir(option(args, '--frontend'))
+      end
+
+      def generate
+        unless File.directory?(@dir)
+          abort "No #{@dir}/ here. Pass --frontend NAME, or run from a Belt app with a frontend."
+        end
+
+        @app_title = app_title
+        @beats = STARTER_BEATS
+        existing = SHOWCASES.find { |file| File.exist?(path(file)) }
+        @showcase_build = "./#{existing || SHOWCASES.first}"
+
+        write('trailer.config.mjs', render('trailer.config.mjs.erb'))
+        write('trailer-titles.css', File.read(File.join(TEMPLATE_DIR, 'trailer-titles.css')))
+        write('trailer-storyboard.md', render('trailer-storyboard.md.erb'))
+        if existing
+          say "  exist   #{path(existing)} (filming that showcase)"
+        elsif !@skip_showcase
+          write_showcase
+        end
+        ignore_output
+        point_agents
+        next_steps
+      end
+
+      def destroy
+        files = %w[trailer.config.mjs trailer-titles.css trailer-storyboard.md]
+        files += SHOWCASE_FILES.map { |f| "scripts/showcase/#{f}" } if generated_showcase?
+        files.each do |file|
+          next unless File.exist?(path(file))
+
+          FileUtils.rm_f(path(file))
+          say "  remove  #{path(file)}"
+        end
+        [path('scripts/showcase'), path('scripts')].each do |dir|
+          FileUtils.rmdir(dir) if File.directory?(dir) && Dir.empty?(dir)
+        end
+      end
+
+      private
+
+      def write_showcase
+        SHOWCASE_FILES.each do |file|
+          template = File.join('showcase', file)
+          body = if File.exist?(File.join(TEMPLATE_DIR, "#{template}.erb"))
+                   render("#{template}.erb")
+                 else
+                   File.read(File.join(TEMPLATE_DIR, template))
+                 end
+          write("scripts/showcase/#{file}", body)
+        end
+      end
+
+      # Ours if its build.mjs is the one this generator writes.
+      def generated_showcase?
+        build = path('scripts/showcase/build.mjs')
+        File.exist?(build) && File.read(build) == File.read(File.join(TEMPLATE_DIR, 'showcase/build.mjs'))
+      end
+
+      def write(file, body)
+        target = path(file)
+        if File.exist?(target) && !@force
+          say "  skip    #{target} (exists; --force to overwrite)"
+          return
+        end
+        FileUtils.mkdir_p(File.dirname(target))
+        File.write(target, body)
+        say "  create  #{target}"
+      end
+
+      # The showcase build and the clips go under tmp/, which shouldn't be committed.
+      def ignore_output
+        gitignore = path('.gitignore')
+        return unless File.exist?(gitignore)
+
+        lines = File.readlines(gitignore, chomp: true)
+        return if lines.any? { |l| %w[tmp tmp/ /tmp /tmp/].include?(l.strip) }
+
+        File.write(gitignore, "#{File.read(gitignore).chomp}\n/tmp/\n")
+        say "  update  #{gitignore} (ignore /tmp/)"
+      end
+
+      # Most trailers are made by AI agents: tell the ones working in this app
+      # where the skill is.
+      def point_agents
+        agents = 'AGENTS.md'
+        return unless File.exist?(agents)
+        return if File.read(agents).include?(AGENTS_MARKER)
+
+        File.write(agents, "#{File.read(agents).chomp}\n\n#{AGENTS_SECTION.gsub('FRONTEND', @dir)}")
+        say "  update  #{agents} (#{AGENTS_MARKER})"
+      end
+
+      def render(template)
+        ERB.new(File.read(File.join(TEMPLATE_DIR, template)), trim_mode: '-').result(binding)
+      end
+
+      def app_title
+        name = JSON.parse(File.read(path('package.json')))['name'] if File.exist?(path('package.json'))
+        name = File.basename(Dir.pwd) if name.to_s.empty? || name == 'frontend'
+        name.to_s.sub(%r{\A@[^/]+/}, '').split(/[-_\s]+/).map(&:capitalize).join(' ').gsub("'", '’')
+      end
+
+      def next_steps
+        say <<~STEPS
+
+          Next:
+            1. Read the skill: belt trailer guide. Write the storyboard in
+               #{path('trailer-storyboard.md')}, then the fixtures it films, then
+               the beats in #{path('trailer.config.mjs')}.
+            2. cd #{@dir} && npm install -D playwright && npx playwright install chromium
+            3. belt trailer film --format wide, then belt trailer cut and belt trailer check
+        STEPS
+      end
+
+      def path(file)
+        File.join(@dir, file)
+      end
+
+      def option(args, flag)
+        index = args.index { |a| a == flag || a.start_with?("#{flag}=") }
+        return nil unless index
+
+        args[index].include?('=') ? args[index].split('=', 2).last : args[index + 1]
+      end
+
+      def say(text)
+        @out.puts(text)
+      end
+    end
+  end
+end

data/lib/belt/trailer/templates/showcase/build.mjs

@@ -0,0 +1,24 @@
+// Builds the showcase (showcase.html) with Vite into tmp/showcase-dist, for
+// belt-trailer to film. API calls go to the showcase's own origin, where the
+// fixture or trailer.config.mjs answers them; nothing reaches a backend.
+import { build } from 'vite';
+import react from '@vitejs/plugin-react';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const frontend = path.resolve(here, '../..');
+export const distDir = path.join(frontend, 'tmp/showcase-dist');
+
+export async function buildShowcase() {
+  process.env.VITE_API_URL = 'http://showcase.local/api';
+  await build({
+    root: here,
+    publicDir: path.join(frontend, 'public'),
+    plugins: [react()],
+    logLevel: 'warn',
+    configFile: false,
+    build: { outDir: distDir, emptyOutDir: true, rollupOptions: { input: path.join(here, 'showcase.html') } },
+  });
+  return { distDir };
+}

data/lib/belt/trailer/templates/showcase/fixtures.js.erb

@@ -0,0 +1,22 @@
+// The states the showcase can show, by name: the route to render and the
+// answers to the API calls it makes, as the server would really send them.
+//
+// Make the trailer's fixtures one story: every shot is the same session at a
+// later moment, with the same records and people, built from one function.
+// A record that changes between two cuts reads as a different session. Give
+// each state change its own fixture: sounds and animations come from the
+// difference between two states, so a missing event is a missing sound.
+
+export const FIXTURES = {
+  home: {
+    path: '/',
+    api: {
+      '/': {
+        title: '<%= @app_title %>',
+        subtitle: 'Your Belt app is running.',
+        stack: { api_gateway: true, lambda: true, dynamodb: true },
+        next_steps: [],
+      },
+    },
+  },
+};

data/lib/belt/trailer/templates/showcase/showcase.html

@@ -0,0 +1,14 @@
+<!DOCTYPE html>
+<!-- The app's screens rendered from fixtures, for belt-trailer. Keep the
+     same fonts and head as the real index.html. -->
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Showcase</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="./showcase.jsx"></script>
+  </body>
+</html>

data/lib/belt/trailer/templates/showcase/showcase.jsx

@@ -0,0 +1,50 @@
+// The showcase: the app rendered from a fixture, chosen by name
+// (?view=<fixture>), with no backend. window.__setView(name) switches to
+// another fixture without reloading, so the app's components see a state
+// change and animate (and play their sounds) as on a real update.
+//
+// Two hooks for the trailer, behind query flags so the showcase stays quiet
+// otherwise:
+//   ?sound=1    mount the app's own sound hooks here, so it plays what it would
+//   window.__…  an app-defined trigger a beat can fire on cue with
+//               fire('__name', ...args), rather than a timer from load
+import React, { useEffect, useState } from 'react';
+import ReactDOM from 'react-dom/client';
+import { MemoryRouter } from 'react-router-dom';
+import App from '../../src/App';
+import '../../src/index.css';
+import { FIXTURES } from './fixtures.js';
+
+const params = new URLSearchParams(location.search);
+// ?sound=1: call your app's sound hooks in Showcase when this is true (it's
+// fixed for the page, so a hook behind it is safe).
+const SOUND = params.get('sound') === '1';
+
+// API calls answered from the current fixture: `api` maps a path (after
+// VITE_API_URL) to its JSON. Anything else goes on to trailer.config.mjs.
+let current = FIXTURES[params.get('view')] || Object.values(FIXTURES)[0];
+const network = window.fetch.bind(window);
+window.fetch = async (input, init) => {
+  const url = new URL(typeof input === 'string' ? input : input.url, location.href);
+  const key = url.pathname.replace(/^\/api/, '') || '/';
+  if (current?.api && key in current.api) {
+    return new Response(JSON.stringify(current.api[key]), { headers: { 'Content-Type': 'application/json' } });
+  }
+  return network(input, init);
+};
+
+function Showcase() {
+  const [view, setView] = useState(params.get('view') || Object.keys(FIXTURES)[0]);
+  useEffect(() => { window.__setView = setView; }, []);
+  const fixture = FIXTURES[view];
+  if (!fixture) return <p>No fixture called {view}. Add it to scripts/showcase/fixtures.js.</p>;
+  current = fixture;
+  // A new path remounts the app; the same path with new data is an update.
+  return (
+    <MemoryRouter key={fixture.path} initialEntries={[fixture.path]}>
+      <App />
+    </MemoryRouter>
+  );
+}
+
+ReactDOM.createRoot(document.getElementById('root')).render(<Showcase />);

data/lib/belt/trailer/templates/trailer-storyboard.md.erb

@@ -0,0 +1,37 @@
+# <%= @app_title %> launch trailer: storyboard
+
+Write this before scripting any beat, and get it agreed. How: `belt trailer guide`
+(the belt-trailer skill, references/storyboard.md). The beats in
+trailer.config.mjs follow this table, by name.
+
+## Who it's for and what it offers
+
+- **Who:** TODO: one sentence; what are they doing when they'd want it?
+- **The offer, in one line:** TODO: usually the site's meta description or store subtitle
+- **What makes it different**, in order of how fast it reads on screen:
+  1. TODO
+- **Not leading with:** TODO (usually the rules, settings or onboarding)
+
+## The cut
+
+TODO: 5–7 beats, 20–30 s. Every product shot is the same session at a later
+moment, built from one fixture function: TODO name it.
+
+| Time | Beat | Fixture(s) | Camera | On screen | Why it's here |
+|---|---|---|---|---|---|
+| 0–3.3 s | `hook` | `home` | wide, then push in on the subject | TODO | something happens in the first second |
+| 3.3–6.8 s | `end` | `home` (blurred) | still | logo · the offer · terms · <%= @url %> | the call to action, held long enough to type |
+
+## Sound
+
+| Beat | Music | Effects the viewer should hear |
+|---|---|---|
+| `hook` | TODO | TODO |
+| `end` | TODO | |
+
+Where every audio file comes from, and whether it can be used in advertising:
+TODO (a person answers this before anything is published).
+
+## Open questions
+
+- TODO

data/lib/belt/trailer/templates/trailer-titles.css

@@ -0,0 +1,22 @@
+/* The trailer's titles, in the app's own look. Loaded after belt-trailer's
+   defaults (engine/titles.html), so anything here wins. Fonts are served from
+   the showcase build, i.e. from public/. */
+
+/* @font-face { font-family: 'Brand'; font-weight: 400 900; src: url(/fonts/brand.woff2) format('woff2'); } */
+
+:root {
+  --title-font: system-ui, sans-serif;
+  --line-font: var(--title-font);
+  --line-weight: 800;
+  --kicker-color: #f5d27a;
+  /* Each word of a title is filled with this, so a gradient reads as metal. */
+  --word-fill: linear-gradient(180deg, #ffffff 0%, #f1f1f1 55%, #cfcfcf 100%);
+  --word-glow: rgba(255, 255, 255, 0.25);
+  --rule: linear-gradient(90deg, transparent, #f5d27a 30%, #fff3c9 50%, #f5d27a 70%, transparent);
+  /* The dark wash behind the words, as r, g, b. */
+  --shade: 9, 6, 16;
+  --end-text: #f4f0e6;
+  --end-muted: #cfc7b4;
+  --url-text: #1d1405;
+  --url-fill: linear-gradient(180deg, #fff1c4 0%, #f5d27a 55%, #d1a23f 100%);
+}

data/lib/belt/trailer/templates/trailer.config.mjs.erb

@@ -0,0 +1,69 @@
+// <%= @app_title %>'s launch trailer: `belt trailer film`, `belt trailer cut`,
+// `belt trailer check`. Start with `belt trailer guide` (how to write the
+// storyboard, fixtures and beats, and review what you film), and see the gem's
+// examples/posh-nosh/ for a finished trailer.
+//
+// Write the storyboard (trailer-storyboard.md) before the beats: five to
+// seven shots, 20–30 s, opening on something happening in the first second
+// and ending on the offer and the address. Hold every title, fully landed,
+// about two seconds.
+
+export default {
+  // The app's screens with no backend: <%= @showcase_build %> builds them,
+  // and ?view=<fixture> picks one (fixtures.js beside it).
+  showcase: { build: '<%= @showcase_build %>', query: { sound: 1 } },
+
+  // Canned answers for any API call a fixture doesn't answer itself. The
+  // first key that matches wins; a key ending in * is a prefix.
+  api: {
+    '/api/*': {},
+  },
+
+  // Where the files behind the sounds the app plays live. If someone can
+  // replace sounds on the live site, add live: { origin, paths }.
+  sounds: { bundled: 'public' },
+
+  titles: {
+    css: './trailer-titles.css',
+    endCard: {
+      logo: null, // e.g. '/images/logo.png', served from public/
+      lines: ['<%= @app_title %> — what it is, in one line', 'Free · No account needed'],
+      url: '<%= @url %>',
+    },
+  },
+
+  // Music starts on the first frame: a silent cold open reads as a broken
+  // video. Name tracks (files in this directory) and say which plays under
+  // each beat; null is silence. cam.mark('hush') in a beat stops it there.
+  music: {
+    tracks: {
+      // theme: 'public/sounds/theme.mp3',
+    },
+    plan: { <%= @beats.map { |b| "#{b}: null" }.join(', ') %> },
+  },
+
+  beats: [
+    // The hook: something happens in the first second.
+    { name: 'hook', view: 'home', play: async ({ cam, ease }) => {
+      await cam.focus('#root', { pad: 0 });
+      await cam.hold(300);
+      // Frame an element after its entrance animation has finished. A push of
+      // more than about 1.5× takes at least 0.9 s.
+      // pad, top, right and bottom are fractions of the subject's size: here
+      // room below it for the words.
+      await cam.focus('h1', { ms: 1200, pad: 0.1, bottom: 2, ease: ease.inOut });
+      await cam.hold(400);
+      // Words sit where nothing important is, never on the subject: side (a
+      // panel on the right of a wide frame), band (across a tall one), top
+      // or bottom.
+      cam.title({ kicker: '<%= @app_title %>', line: 'Say what it does', place: 'bottom' });
+      await cam.hold(2600);
+    } },
+    // The end card over the app, softened behind it.
+    { name: 'end', view: 'home', css: '#root { filter: blur(5px) brightness(0.6); }', play: async ({ cam }) => {
+      await cam.focus('#root', { pad: 0 });
+      cam.endCard();
+      await cam.hold(3500);
+    } },
+  ],
+};

data/lib/belt/trailer/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Belt
+  module Trailer
+    VERSION = '0.1.0'
+  end
+end

data/lib/belt/trailer.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require_relative 'trailer/version'
+
+module Belt
+  # Films a launch trailer of a web app from its own screens and sounds.
+  #
+  # The filming, camera, titles, sound capture, cut and checks are a Node
+  # engine (engine/) that knows nothing about Belt: it takes an app directory
+  # with a trailer.config.mjs and loads the app's own Playwright from there.
+  # It runs from the gem's directory and is never copied into the app. This
+  # Ruby side is the Belt layer: `belt generate trailer` and `belt trailer`.
+  module Trailer
+    class Error < StandardError; end
+
+    ROOT = File.expand_path('../..', __dir__)
+    ENGINE_DIR = File.join(ROOT, 'engine')
+    # The agent skill, also installable with `npx skills add stowzilla/belt-trailer`.
+    SKILL_DIR = File.join(ROOT, 'skills', 'belt-trailer')
+    ENGINE_BIN = File.join(ENGINE_DIR, 'bin', 'trailer.mjs')
+    CONFIG_FILE = 'trailer.config.mjs'
+    TOOLS = {
+      'node' => 'Node 20 or later (https://nodejs.org)',
+      'ffmpeg' => 'ffmpeg, built with drawtext (e.g. `brew install ffmpeg`, `apt install ffmpeg`)',
+      'ffprobe' => 'ffprobe (comes with ffmpeg)'
+    }.freeze
+
+    module_function
+
+    # The argv that runs an engine command on an app directory.
+    def engine_command(command, app_dir, args = [])
+      ['node', ENGINE_BIN, command, '--app', app_dir, *args]
+    end
+
+    # What's missing to film in `app_dir`, as messages; empty when ready.
+    def missing_requirements(app_dir, config: CONFIG_FILE)
+      missing = TOOLS.reject { |tool, _| executable?(tool) }.values
+      return missing << "#{app_dir}/ (no such directory)" unless File.directory?(app_dir)
+
+      unless playwright?(app_dir)
+        missing << "Playwright in #{app_dir} " \
+                   "(cd #{app_dir} && npm install -D playwright && npx playwright install chromium)"
+      end
+      unless File.exist?(File.expand_path(config, app_dir))
+        missing << "#{File.join(app_dir, config)} (run `belt generate trailer`)"
+      end
+      missing
+    end
+
+    # Whether Node would find Playwright from `app_dir`: in its node_modules
+    # or any parent's, as with a hoisted workspace.
+    def playwright?(app_dir)
+      dir = File.expand_path(app_dir)
+      loop do
+        return true if File.exist?(File.join(dir, 'node_modules', 'playwright', 'package.json'))
+        return false if File.dirname(dir) == dir
+
+        dir = File.dirname(dir)
+      end
+    end
+
+    def executable?(name)
+      ENV.fetch('PATH', '').split(File::PATH_SEPARATOR).any? do |dir|
+        path = File.join(dir, name)
+        File.file?(path) && File.executable?(path)
+      end
+    end
+  end
+end

data/lib/belt-trailer.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative 'belt/trailer'