@fullstackcraftllc/codevideo-cli 0.0.7

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 CodeVideo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,11 @@
+# CodeVideo CLI
+
+Cross-platform npm distribution of the CodeVideo video rendering CLI.
+
+```shell
+npx @fullstackcraftllc/codevideo-cli doctor
+npx @fullstackcraftllc/codevideo-cli install-browser
+npx @fullstackcraftllc/codevideo-cli --version
+```
+
+Rendering requires FFmpeg on `PATH` (or `CODEVIDEO_FFMPEG_PATH`). Chrome is detected automatically; if none is installed, run `codevideo-cli install-browser`.

package/bin/codevideo-cli.js

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+
+import { spawn } from "node:child_process";
+import { runDoctor } from "../doctor.js";
+import { installBrowser } from "../install-browser.js";
+import { resolveCodeVideoCliRuntime } from "../index.js";
+
+const args = process.argv.slice(2);
+
+if (args[0] === "doctor") {
+  process.exitCode = await runDoctor();
+} else if (args[0] === "install-browser") {
+  await installBrowser();
+} else {
+  const runtime = resolveCodeVideoCliRuntime();
+  const child = spawn(runtime.binaryPath, args, {
+    cwd: process.cwd(),
+    env: runtime.env,
+    stdio: "inherit"
+  });
+
+  for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"]) {
+    process.on(signal, () => child.kill(signal));
+  }
+  child.once("error", (error) => {
+    console.error(`Failed to start CodeVideo CLI: ${error.message}`);
+    process.exitCode = 1;
+  });
+  child.once("exit", (code, signal) => {
+    if (signal) process.kill(process.pid, signal);
+    else process.exitCode = code ?? 1;
+  });
+}

package/doctor.js

@@ -0,0 +1,35 @@
+import fs from "node:fs";
+import { spawnSync } from "node:child_process";
+import { createRequire } from "node:module";
+import { resolveCodeVideoCliRuntime } from "./index.js";
+
+const require = createRequire(import.meta.url);
+const runtimePaths = require("./runtime/runtimePaths.js");
+
+function checkWritableDirectory(directory) {
+  fs.mkdirSync(directory, { recursive: true });
+  fs.accessSync(directory, fs.constants.W_OK);
+}
+
+export async function runDoctor(options = {}) {
+  const checks = [];
+  try {
+    const runtime = resolveCodeVideoCliRuntime(options);
+    const version = spawnSync(runtime.binaryPath, ["--version"], { env: runtime.env, encoding: "utf8" });
+    if (version.status !== 0) throw new Error(version.stderr || "native binary version check failed");
+    checks.push(["native binary", runtime.binaryPath]);
+    checks.push(["Puppeteer runner", runtime.runnerPath]);
+    checks.push(["Chrome", runtimePaths.resolveChromeExecutable()]);
+    checks.push(["FFmpeg", runtimePaths.resolveFfmpegExecutable()]);
+    for (const directory of [runtime.workDir, runtime.logDir, runtime.outputDir]) {
+      checkWritableDirectory(directory);
+    }
+    checks.push(["writable directories", `${runtime.workDir}, ${runtime.logDir}, ${runtime.outputDir}`]);
+    for (const [name, value] of checks) console.log(`✓ ${name}: ${value}`);
+    return 0;
+  } catch (error) {
+    for (const [name, value] of checks) console.log(`✓ ${name}: ${value}`);
+    console.error(`✗ ${error.message}`);
+    return 1;
+  }
+}

package/index.d.ts

@@ -0,0 +1,19 @@
+export interface CodeVideoCliRuntimeOptions {
+  platform?: NodeJS.Platform;
+  arch?: string;
+  env?: NodeJS.ProcessEnv;
+  binaryPath?: string;
+  runnerPath?: string;
+}
+
+export interface CodeVideoCliRuntime {
+  binaryPath: string;
+  runnerPath: string;
+  workDir: string;
+  logDir: string;
+  outputDir: string;
+  env: NodeJS.ProcessEnv;
+}
+
+export declare function getCodeVideoCliPlatformPackage(platform?: NodeJS.Platform, arch?: string): string;
+export declare function resolveCodeVideoCliRuntime(options?: CodeVideoCliRuntimeOptions): CodeVideoCliRuntime;

package/index.js

@@ -0,0 +1,86 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
+
+const require = createRequire(import.meta.url);
+const packageRoot = path.dirname(fileURLToPath(import.meta.url));
+
+const platformPackages = {
+  "darwin-arm64": "@fullstackcraftllc/codevideo-cli-darwin-arm64",
+  "darwin-x64": "@fullstackcraftllc/codevideo-cli-darwin-x64",
+  "linux-arm64": "@fullstackcraftllc/codevideo-cli-linux-arm64",
+  "linux-x64": "@fullstackcraftllc/codevideo-cli-linux-x64",
+  "win32-arm64": "@fullstackcraftllc/codevideo-cli-win32-arm64",
+  "win32-x64": "@fullstackcraftllc/codevideo-cli-win32-x64"
+};
+
+export function getCodeVideoCliPlatformPackage(platform = process.platform, arch = process.arch) {
+  const packageName = platformPackages[`${platform}-${arch}`];
+  if (!packageName) {
+    throw new Error(`Unsupported CodeVideo CLI platform: ${platform}-${arch}`);
+  }
+  return packageName;
+}
+
+function validateExecutable(candidate, label, platform) {
+  const stat = fs.statSync(candidate, { throwIfNoEntry: false });
+  if (!stat?.isFile()) throw new Error(`${label} is not a file: ${candidate}`);
+  if (platform !== "win32") {
+    fs.accessSync(candidate, fs.constants.X_OK);
+  }
+}
+
+export function resolveCodeVideoCliRuntime(options = {}) {
+  const platform = options.platform || process.platform;
+  const arch = options.arch || process.arch;
+  const env = options.env || process.env;
+  let binaryPath = options.binaryPath || env.PATH_TO_CODEVIDEO_CLI;
+
+  if (binaryPath) {
+    binaryPath = path.resolve(binaryPath);
+  } else {
+    const platformPackage = getCodeVideoCliPlatformPackage(platform, arch);
+    let platformRoot;
+    try {
+      platformRoot = path.dirname(require.resolve(`${platformPackage}/package.json`));
+    } catch (error) {
+      throw new Error(
+        `The optional package ${platformPackage} is missing. ` +
+        "Reinstall @fullstackcraftllc/codevideo-cli without --omit=optional.",
+        { cause: error }
+      );
+    }
+    binaryPath = path.join(platformRoot, "bin", platform === "win32" ? "codevideo-cli.exe" : "codevideo-cli");
+  }
+
+  validateExecutable(binaryPath, "CodeVideo CLI", platform);
+
+  const runnerPath = path.resolve(
+    options.runnerPath || env.CODEVIDEO_PUPPETEER_RUNNER_PATH || path.join(packageRoot, "runtime", "recordVideoV3.js")
+  );
+  if (!fs.statSync(runnerPath, { throwIfNoEntry: false })?.isFile()) {
+    throw new Error(`CodeVideo Puppeteer runner is missing: ${runnerPath}`);
+  }
+
+  const cacheRoot = path.join(os.homedir(), ".cache", "codevideo");
+  const workDir = path.resolve(env.CODEVIDEO_WORK_DIR || path.join(os.tmpdir(), "codevideo", "v3"));
+  const logDir = path.resolve(env.CODEVIDEO_LOG_DIR || path.join(cacheRoot, "logs"));
+  const outputDir = path.resolve(env.CODEVIDEO_OUTPUT_DIR || process.cwd());
+
+  return {
+    binaryPath,
+    runnerPath,
+    workDir,
+    logDir,
+    outputDir,
+    env: {
+      ...env,
+      CODEVIDEO_PUPPETEER_RUNNER_PATH: runnerPath,
+      CODEVIDEO_WORK_DIR: workDir,
+      CODEVIDEO_LOG_DIR: logDir,
+      CODEVIDEO_OUTPUT_DIR: outputDir
+    }
+  };
+}

package/install-browser.js

@@ -0,0 +1,34 @@
+import path from "node:path";
+import { createRequire } from "node:module";
+import {
+  Browser,
+  BrowserTag,
+  detectBrowserPlatform,
+  install,
+  resolveBuildId
+} from "@puppeteer/browsers";
+
+const require = createRequire(import.meta.url);
+const { browserCacheDir } = require("./runtime/runtimePaths.js");
+
+export async function installBrowser(options = {}) {
+  const browsers = options.browsers || {
+    detectBrowserPlatform,
+    install,
+    resolveBuildId
+  };
+  const platform = browsers.detectBrowserPlatform();
+  if (!platform) throw new Error(`Unsupported browser platform: ${process.platform}/${process.arch}`);
+  const cacheDir = path.resolve(browserCacheDir(options.env || process.env));
+  const buildId = await browsers.resolveBuildId(Browser.CHROME, platform, BrowserTag.STABLE);
+  const installed = await browsers.install({
+    browser: Browser.CHROME,
+    buildId,
+    buildIdAlias: BrowserTag.STABLE,
+    cacheDir,
+    platform,
+    downloadProgressCallback: "default"
+  });
+  console.log(`Chrome for Testing installed at ${installed.executablePath}`);
+  return installed.executablePath;
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@fullstackcraftllc/codevideo-cli",
+  "version": "0.0.7",
+  "description": "Cross-platform npm distribution of the CodeVideo CLI.",
+  "type": "module",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.js"
+    }
+  },
+  "bin": {
+    "codevideo-cli": "bin/codevideo-cli.js"
+  },
+  "files": [
+    "bin/",
+    "runtime/",
+    "index.js",
+    "index.d.ts",
+    "doctor.js",
+    "install-browser.js",
+    "LICENSE",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@puppeteer/browsers": "^2.10.9",
+    "puppeteer-stream": "^3.0.22",
+    "yargs": "^17.7.2"
+  },
+  "optionalDependencies": {
+    "@fullstackcraftllc/codevideo-cli-darwin-arm64": "0.0.7",
+    "@fullstackcraftllc/codevideo-cli-darwin-x64": "0.0.7",
+    "@fullstackcraftllc/codevideo-cli-linux-arm64": "0.0.7",
+    "@fullstackcraftllc/codevideo-cli-linux-x64": "0.0.7",
+    "@fullstackcraftllc/codevideo-cli-win32-arm64": "0.0.7",
+    "@fullstackcraftllc/codevideo-cli-win32-x64": "0.0.7"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/codevideo/codevideo-cli.git",
+    "directory": "npm/packages/codevideo-cli"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/runtime/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}

package/runtime/recordVideoV3.js

@@ -0,0 +1,245 @@
+const { launch, getStream, wss } = require("puppeteer-stream");
+const fs = require("fs");
+const path = require("path");
+const yargs = require('yargs/yargs');
+const { hideBin } = require('yargs/helpers');
+const { resolveChromeExecutable } = require('./runtimePaths');
+
+// define sleep helper function
+const sleep = ms => new Promise(res => setTimeout(res, ms));
+
+// Parse command line arguments
+const argv = yargs(hideBin(process.argv))
+  .option('uuid', {
+    type: 'string',
+    description: 'Path to the manifest file'
+  })
+  .option('os', {
+    type: 'string',
+    default: 'linux',
+    description: 'Operating system (linux or mac)'
+  })
+  .option('resolution', {
+    type: 'string',
+    default: '1080p',
+    description: 'Video resolution (1080p or 4K)'
+  })
+  .option('orientation', {
+    type: 'string',
+    default: 'landscape',
+    description: 'Video orientation (landscape or portrait)'
+  })
+  .option('debug', {
+    type: 'boolean',
+    default: false,
+    description: 'Run in non-headless mode for debugging'
+  })
+  .option('output-webm', {
+    type: 'string',
+    description: 'Absolute output path for the recorded WebM file'
+  })
+  .option('manifest-path', {
+    type: 'string',
+    description: 'Absolute path to the render manifest'
+  })
+  .argv;
+
+// parse uuid, resolution and orientation from command line arguments
+const uuid = argv.uuid;
+const os = argv.os;
+const resolution = argv.resolution;
+const orientation = argv.orientation;
+const debug = argv.debug;
+
+// set width and height based on resolution and orientation
+let width, height;
+if (resolution === '4K') {
+    width = orientation === 'landscape' ? 3840 : 2160;
+    height = orientation === 'landscape' ? 2160 : 3840;
+} else if (resolution === '1080p') {
+    width = orientation === 'landscape' ? 1920 : 1080;
+    height = orientation === 'landscape' ? 1080 : 1920;
+}
+// if no manifest is provided, exit
+if (!uuid) {
+    console.error("Please provide a manifest file path.");
+    process.exit(1);
+}
+
+async function recordVideoV3() {
+    console.log("Starting recording for UUID: ", uuid);
+    console.log("Debug mode:", debug ? "ENABLED - Browser will be visible" : "disabled");
+
+    const outputWebm = argv.outputWebm
+        ? path.resolve(argv.outputWebm)
+        : path.join(__dirname, `../../tmp/v3/video/${uuid}.webm`);
+    fs.mkdirSync(path.dirname(outputWebm), { recursive: true });
+    const file = fs.createWriteStream(outputWebm);
+
+    console.log("Launching browser with resolution:", width, "x", height, orientation, width === 3840 ? " (4K)" : " (1080p)");
+
+    const browser = await launch({
+        dumpio: true,
+        startDelay: 1000,
+        executablePath: resolveChromeExecutable(),
+        headless: debug ? false : "new", // Use non-headless mode when debugging
+        defaultViewport: { width, height },
+        args: [
+            `--window-size=${width},${height}`,
+            '--start-fullscreen',
+            // `--ozone-override-screen-size=${width},${height}`, // for linux
+            '--no-sandbox', // Chrome's sandbox can't init as root (server/systemd) -> instant "Target closed" without this
+            '--disable-dev-shm-usage', // avoid crashes from a small /dev/shm on servers
+            '--autoplay-policy=no-user-gesture-required',
+            '--enable-extensions',
+            // '--disable-web-security',
+            // '--enable-logging=stderr',  // Enable detailed logging
+            '--v=1',                    // Increase verbosity level
+            '--allowlisted-extension-id=jjndjgheafjngoipoacpjgeicjeomjli', // allowlist the puppeteer-stream extension
+        ],
+    });
+
+    const page = await browser.newPage();
+
+    if (argv.manifestPath) {
+        const manifestPath = path.resolve(argv.manifestPath);
+        await page.setRequestInterception(true);
+        page.on('request', request => {
+            const requestedUrl = new URL(request.url());
+            const isManifestRequest = requestedUrl.hostname === 'localhost'
+                && requestedUrl.port === '7000'
+                && requestedUrl.pathname === '/get-manifest-v3';
+            if (!isManifestRequest) {
+                request.continue();
+                return;
+            }
+            try {
+                request.respond({
+                    status: 200,
+                    contentType: 'application/json',
+                    headers: { 'Access-Control-Allow-Origin': '*' },
+                    body: fs.readFileSync(manifestPath)
+                });
+            } catch (error) {
+                console.error(`Unable to read manifest at ${manifestPath}:`, error);
+                request.respond({ status: 500, body: 'Manifest unavailable' });
+            }
+        });
+    }
+
+    // Log domcontentloaded
+    page.once('domcontentloaded', () => {
+        console.log('DOM content loaded');
+    });
+
+    // Log load
+    page.once('load', () => {
+        console.log('Page fully loaded');
+    });
+
+    // Log all browser console messages.
+    page.on('console', msg => {
+        console.log('BROWSER LOG:', msg.text());
+    });
+
+    // Log page errors
+    page.on('pageerror', error => {
+        console.log('PAGE ERROR:', error.message);
+    });
+
+    // Log network failures
+    page.on('requestfailed', req => {
+        console.log('REQUEST FAILED:', req.url(), req.failure().errorText);
+    });
+
+    // Create a promise that resolves when the final progress update is received.
+    let resolveFinalProgress;
+    const finalProgressPromise = new Promise(resolve => {
+        resolveFinalProgress = resolve;
+    });
+
+    // Expose __onActionProgress so that progress stats from the client are logged in Node.
+    // When a final progress update is received, we resolve the promise.
+    await page.exposeFunction('__onActionProgress', (progress) => {
+        console.log("Progress update:", progress);
+        // Check if this progress update indicates completion.
+        if (progress.progress === "100.0" || progress.currentAction >= progress.totalActions) {
+            resolveFinalProgress();
+        }
+    });
+    console.log("added __onActionProgress");
+
+    // Navigate to the puppeteer page.
+    await page.setViewport({ width: 0, height: 0 });
+
+    const url = `http://localhost:7001/v3?uuid=${uuid}`;
+    console.log(`Navigating to ${url}`);
+    await page.goto(url);
+    console.log("Page navigated");
+
+    // click body to trigger interaction
+    await page.click("body");
+    console.log("Clicked body");
+
+    // Inject CSS to remove margins/padding so the video fills the viewport
+    await page.addStyleTag({ content: `body { margin: 0; padding: 0; }` });
+    console.log("Added style tag");
+
+    const videoConstraints = {
+        mandatory: {
+            minWidth: width,
+            minHeight: height,
+            maxWidth: width,
+            maxHeight: height,
+        },
+    };
+
+    // Start the stream and pipe it to a file.
+    const stream = await getStream(page, {
+        audio: true,
+        video: true,
+        mimeType: "video/webm", // WebM is well-supported for high-quality web video
+        audioBitsPerSecond: 384000, // 384 kbps for high-quality stereo audio
+        videoBitsPerSecond: width === 3840 ?  80000000: 20000000, // 80 Mpbs for 4K; 20 Mbps (20,000 kbps) for high-quality 1080p video
+        frameSize: 16, // approx 60 FPS
+        videoConstraints
+    });
+    stream.pipe(file);
+    console.log("Recording started");
+
+    // Wait a moment before triggering start.
+    await sleep(1000);
+
+    // Send signal to react component to start recording
+    console.log("Triggering recording start...");
+    await page.evaluate(() => {
+        window.__startRecording();
+    })
+
+    // Wait until the client sends a final progress update.
+    await finalProgressPromise;
+
+    // Wait a moment before stopping the recording.
+    await sleep(1000);
+
+    // Once complete, tear down the recording.
+    console.log("Final progress received. Stopping recording...");
+    
+    // If debug mode is enabled, wait longer to allow inspection
+    if (debug) {
+        console.log("Debug mode: Waiting 5 seconds before closing browser...");
+        await sleep(5000);
+    }
+    
+    await stream.destroy();
+    file.close();
+    console.log("Recording finished");
+
+    await browser.close();
+    (await wss).close();
+}
+
+recordVideoV3().catch(err => {
+    console.error("Error during recording:", err);
+    process.exitCode = 1;
+});

package/runtime/runtimePaths.js

@@ -0,0 +1,126 @@
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+
+function isExecutableFile(candidate) {
+  if (!candidate) return false;
+  try {
+    const stat = fs.statSync(candidate);
+    if (!stat.isFile()) return false;
+    if (process.platform !== "win32") {
+      fs.accessSync(candidate, fs.constants.X_OK);
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function findOnPath(names) {
+  const entries = (process.env.PATH || "").split(path.delimiter).filter(Boolean);
+  const extensions = process.platform === "win32"
+    ? (process.env.PATHEXT || ".EXE;.CMD;.BAT").split(";")
+    : [""];
+  for (const name of names) {
+    for (const entry of entries) {
+      for (const extension of extensions) {
+        const candidate = path.join(entry, process.platform === "win32" ? `${name}${extension}` : name);
+        if (isExecutableFile(candidate)) return candidate;
+      }
+    }
+  }
+  return null;
+}
+
+function chromeSubpath() {
+  const macApp = "Google Chrome for Testing.app/Contents/MacOS/Google Chrome for Testing";
+  if (process.platform === "darwin") {
+    return process.arch === "arm64" ? `chrome-mac-arm64/${macApp}` : `chrome-mac-x64/${macApp}`;
+  }
+  if (process.platform === "win32") return "chrome-win64/chrome.exe";
+  return "chrome-linux64/chrome";
+}
+
+function findCachedChrome(chromeRoot) {
+  if (!fs.existsSync(chromeRoot)) return null;
+  const builds = fs.readdirSync(chromeRoot)
+    .map((name) => path.join(chromeRoot, name))
+    .filter((candidate) => {
+      try { return fs.statSync(candidate).isDirectory(); } catch { return false; }
+    })
+    .sort()
+    .reverse();
+  for (const build of builds) {
+    const candidate = path.join(build, chromeSubpath());
+    if (isExecutableFile(candidate)) return candidate;
+  }
+  return null;
+}
+
+function browserCacheDir(env = process.env) {
+  return env.CODEVIDEO_BROWSER_CACHE_DIR || path.join(os.homedir(), ".cache", "codevideo", "chrome");
+}
+
+function systemChromeCandidates() {
+  if (process.platform === "darwin") {
+    return [
+      "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+      "/Applications/Google Chrome for Testing.app/Contents/MacOS/Google Chrome for Testing",
+      path.join(os.homedir(), "Applications/Google Chrome.app/Contents/MacOS/Google Chrome"),
+    ];
+  }
+  if (process.platform === "win32") {
+    return [
+      process.env.PROGRAMFILES && path.join(process.env.PROGRAMFILES, "Google/Chrome/Application/chrome.exe"),
+      process.env["PROGRAMFILES(X86)"] && path.join(process.env["PROGRAMFILES(X86)"], "Google/Chrome/Application/chrome.exe"),
+      process.env.LOCALAPPDATA && path.join(process.env.LOCALAPPDATA, "Google/Chrome/Application/chrome.exe"),
+    ].filter(Boolean);
+  }
+  return [];
+}
+
+function resolveChromeExecutable() {
+  if (process.env.CODEVIDEO_CHROME_PATH) {
+    if (!isExecutableFile(process.env.CODEVIDEO_CHROME_PATH)) {
+      throw new Error(`CODEVIDEO_CHROME_PATH is not an executable file: ${process.env.CODEVIDEO_CHROME_PATH}`);
+    }
+    return process.env.CODEVIDEO_CHROME_PATH;
+  }
+
+  const managed = findCachedChrome(path.join(browserCacheDir(), "chrome"));
+  if (managed) return managed;
+
+  const legacy = findCachedChrome(path.join(__dirname, "chrome"));
+  if (legacy) return legacy;
+
+  for (const candidate of systemChromeCandidates()) {
+    if (isExecutableFile(candidate)) return candidate;
+  }
+
+  const fromPath = findOnPath(["google-chrome-stable", "google-chrome", "chromium", "chromium-browser"]);
+  if (fromPath) return fromPath;
+
+  throw new Error(
+    `Chrome was not found for ${process.platform}/${process.arch}. ` +
+    "Set CODEVIDEO_CHROME_PATH or run `codevideo-cli install-browser`."
+  );
+}
+
+function resolveFfmpegExecutable() {
+  if (process.env.CODEVIDEO_FFMPEG_PATH) {
+    if (!path.isAbsolute(process.env.CODEVIDEO_FFMPEG_PATH) || !isExecutableFile(process.env.CODEVIDEO_FFMPEG_PATH)) {
+      throw new Error(`CODEVIDEO_FFMPEG_PATH is not an absolute executable file: ${process.env.CODEVIDEO_FFMPEG_PATH}`);
+    }
+    return process.env.CODEVIDEO_FFMPEG_PATH;
+  }
+  const executable = findOnPath(["ffmpeg"]);
+  if (executable) return executable;
+  throw new Error("FFmpeg was not found. Install ffmpeg on PATH or set CODEVIDEO_FFMPEG_PATH.");
+}
+
+module.exports = {
+  browserCacheDir,
+  isExecutableFile,
+  resolveChromeExecutable,
+  resolveFfmpegExecutable,
+};