@vfrey/vfrey 0.0.1 → 1.0.0-beta.0

package/src/pipeline/topics-source.ts

@@ -0,0 +1,90 @@
+// The `vfrey-topics` series source (spec 016): the value is a niche id. The source stage reads the ranked topics, skips the ones this series already made a video about,
+// and hands the rest on as candidates with their evidence. Any failure skips the source with a warning on the run; it never stops the tick.
+import { ApiConfigError } from "../api/config.js";
+import { ApiFailure, clean } from "../api/client.js";
+import { fetchTopics } from "../api/topics.js";
+import { insertWarningOnce } from "../queue/desk-ops.js";
+import { log } from "../log.js";
+import type { Candidate } from "@vfrey/contracts";
+import type { Topic } from "@vfrey/contracts";
+import type { JobRecord } from "../queue/store.js";
+import type { Runtime } from "./run.js";
+
+/** What the job payload carries under `topic`: enough for the agent or script to cite the evidence. */
+export interface UsedTopic {
+  source: "vfrey-topics";
+  id: string;
+  niche: string;
+  title: string;
+  keywords: string[];
+  platforms: string[];
+  score: number;
+  evidence: Topic["evidence"];
+}
+
+export const topicFingerprint = (niche: string, id: string): string => `vfrey-topic:${niche}:${id}`;
+
+const norm = (text: unknown): string => String(text ?? "").trim().toLowerCase().replace(/\s+/g, " ");
+
+/** Topic ids and titles this series already used or made a video about, read from its earlier jobs. */
+export function postedTopics(runtime: Pick<Runtime, "store">, accountId: string): { ids: Set<string>; titles: Set<string> } {
+  const ids = new Set<string>();
+  const titles = new Set<string>();
+  const rows = runtime.store.db.prepare(`SELECT payload FROM jobs WHERE account_id = ? ORDER BY created_at DESC LIMIT 500`).all(accountId) as Array<{ payload: string }>;
+  for (const row of rows) {
+    try {
+      const payload = JSON.parse(row.payload) as { topic?: { id?: string; niche?: string; title?: string }; candidates?: Array<{ title?: string }>; content?: { title?: string; candidate?: { title?: string } } | null };
+      if (payload.topic?.id) ids.add(`${payload.topic.niche ?? ""}:${payload.topic.id}`);
+      if (payload.topic?.title) titles.add(norm(payload.topic.title));
+      for (const candidate of payload.candidates ?? []) if (candidate.title) titles.add(norm(candidate.title));
+      if (payload.content?.title) titles.add(norm(payload.content.title));
+      if (payload.content?.candidate?.title) titles.add(norm(payload.content.candidate.title));
+    } catch {
+      /* an unreadable payload is not a posted topic */
+    }
+  }
+  return { ids, titles };
+}
+
+function excerptOf(topic: Topic): string {
+  const lines = [`Trending on ${topic.platforms.join(", ") || "social platforms"} (score ${Number(topic.score).toFixed(1)}). Keywords: ${topic.keywords.join(", ")}.`];
+  for (const item of topic.evidence) lines.push(`Evidence: ${item.url}${typeof item.views === "number" ? ` (${item.views} views)` : ""}${item.why ? ` - ${item.why}` : ""}`);
+  return clean(lines.join("\n")).slice(0, 1500);
+}
+
+/** The top topics for each `vfrey-topics` source of this series, best first, minus the ones already posted. */
+export async function topicCandidates(runtime: Runtime, account: { id: string }, job?: Pick<JobRecord, "id" | "attempt">): Promise<Array<{ candidate: Candidate; topic: UsedTopic }>> {
+  const sources = runtime.store.db.prepare(`SELECT id, value FROM desk_sources WHERE series_id = ? AND kind = 'vfrey-topics' ORDER BY rowid`).all(account.id) as Array<{ id: string; value: string }>;
+  if (sources.length === 0) return [];
+  const out: Array<{ candidate: Candidate; topic: UsedTopic }> = [];
+  const posted = postedTopics(runtime, account.id);
+  for (const source of sources) {
+    const before = out.length;
+    try {
+      const answer = await fetchTopics({ env: runtime.env, fetch: (url, init) => runtime.fetchImpl(url, init) }, { niche: source.value, limit: 20 });
+      const ranked = [...answer.topics].sort((a, b) => b.score - a.score);
+      for (const topic of ranked) {
+        if (posted.ids.has(`${topic.niche ?? source.value}:${topic.id}`) || posted.ids.has(`${source.value}:${topic.id}`) || posted.titles.has(norm(topic.title))) continue;
+        const url = topic.evidence.map((item) => item.url).find((u) => /^https?:\/\//i.test(u)) ?? `vfrey-topics:${source.value}/${topic.id}`;
+        out.push({
+          candidate: { fingerprint: topicFingerprint(source.value, topic.id), provider: "manual", title: clean(topic.title), url, excerpt: excerptOf(topic), publishedAt: topic.lastSeen ?? null },
+          topic: { source: "vfrey-topics", id: topic.id, niche: topic.niche ?? source.value, title: clean(topic.title), keywords: topic.keywords, platforms: topic.platforms, score: topic.score, evidence: topic.evidence },
+        });
+      }
+      runtime.store.recordSourceFetch(source.id, { at: runtime.now(), count: out.length - before, code: null, status: "ok" });
+    } catch (error) {
+      const known = error instanceof ApiFailure || error instanceof ApiConfigError;
+      const message = known ? `${error.message} Fix: ${error.fix}` : `vfrey Topics failed: ${error instanceof Error ? clean(error.message) : "unknown error"}`;
+      const text = `vfrey Topics source "${source.value}" was skipped. ${message}`;
+      log("warn", "topics source skipped", { accountId: account.id, niche: source.value, code: error instanceof ApiFailure ? error.code : undefined });
+      runtime.store.recordSourceFetch(source.id, { at: runtime.now(), count: null, code: "topics_unavailable", status: "skipped" });
+      if (job) runtime.store.recordEvent(job.id, { stage: "source", status: "warning", code: "topics_unavailable", message: text, durationMs: null, attempt: job.attempt });
+      try {
+        insertWarningOnce(runtime.store.db, { accountId: account.id, jobId: job?.id ?? null, code: "topics_unavailable", message: text });
+      } catch {
+        /* a warning that cannot be written must not stop the tick */
+      }
+    }
+  }
+  return out;
+}

package/src/product/commands.ts

@@ -0,0 +1,296 @@
+import { spawn } from "node:child_process";
+import path from "node:path";
+import { acquireStartLock, canListen, deskOf, findDashboard, pickPort, removeDashboardRecord, writeDashboardRecord } from "../dashboard-link.js";
+import { startDashboard } from "../desk/http.js";
+import { runDeskTick } from "../desk/tick.js";
+import { dataDirFor, resolveHome } from "../home.js";
+import { Store } from "../queue/store.js";
+import { readProductConfig } from "./config-file.js";
+import { chooseEngine, readMachineEngine, readProjectEngine, unavailableMessage } from "./engine-choice.js";
+import { allEngineStatuses, DEFAULT_ENGINE, engineById, engineStatus, statusText, type EngineId, type EngineProbes } from "./engines.js";
+import { defaultProbes } from "./probes.js";
+import * as verbs from "../desk/verbs.js";
+import { forcedFailure, renderHtmlEngine } from "../render/html-engine.js";
+import { appendInsight } from "./insights.js";
+import { configFile, insightFile, productDir } from "./paths.js";
+import { renderVerticalShort } from "../render/vertical-short.js";
+import { failedMessage } from "./engine-choice.js";
+import { renderChosenEngine } from "./render-video.js";
+import { buildShort, parseComposition } from "./short.js";
+import { runSceneCommand, runSceneRender } from "../scene/command.js";
+import { formatUpdatePlan, updateCommands, updateInstallRoot } from "./update.js";
+
+export interface CommandIo {
+  env: NodeJS.ProcessEnv;
+  stdout: (text: string) => void;
+  stderr: (text: string) => void;
+  renderLocal?: (outputPath: string, props: import("@vfrey/contracts").RenderProps, engine: EngineId) => Promise<void>;
+  upload?: () => Promise<void>;
+  probes?: EngineProbes;
+  /** Test hook. The CLI omits this and the dashboard stays up. */
+  onListen?: (port: number, close: () => Promise<void>) => Promise<void>;
+  apply?: (command: string, cwd: string) => Promise<void>;
+}
+
+function flag(argv: string[], name: string): string | null {
+  const index = argv.indexOf(name);
+  if (index === -1) return null;
+  return argv[index + 1] ?? null;
+}
+
+function hasFlag(argv: string[], name: string): boolean {
+  return argv.includes(name);
+}
+
+export { defaultProbes };
+
+const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
+
+/**
+ * `vfrey dashboard`. Without --port it serves this desk once: when this desk's dashboard is already listening it prints
+ * that address and exits 0. It picks the recorded port if free, else 4317 (VFREY_DASHBOARD_PORT), else the next free
+ * port. --port forces a port (0 for any) and never reuses.
+ */
+async function runDashboard(argv: string[], io: CommandIo): Promise<number> {
+  const portFlag = flag(argv, "--port");
+  const forced = portFlag !== null;
+  const forcedPort = Number(portFlag);
+  if (forced && (!Number.isInteger(forcedPort) || forcedPort < 0 || forcedPort > 65535)) {
+    io.stderr(`✗ ${portFlag} is not a port.\nFix: pass --port <n> between 0 and 65535.\n`);
+    return 1;
+  }
+  const home = resolveHome(io.env);
+  const desk = deskOf(home);
+  const dataDir = home.dataDir;
+  const ready = (port: number) => {
+    // The ready line goes to stdout at once for whoever reads the output, and to stderr for whoever captures logs.
+    io.stdout(`vfrey dashboard http://127.0.0.1:${port}\n`);
+    io.stderr(`vfrey dashboard http://127.0.0.1:${port}\n`);
+  };
+  const listening = async (): Promise<number | null> => {
+    const origin = await findDashboard(desk, io.env);
+    return origin ? Number(new URL(origin).port) : null;
+  };
+  let release: (() => void) | null = null;
+  if (!forced) {
+    const up = await listening();
+    if (up !== null) {
+      ready(up);
+      return 0;
+    }
+    // Another start in flight (a tick and `open` at once) holds the lock: wait for its dashboard instead of making a second.
+    release = acquireStartLock(dataDir);
+    for (let waited = 0; !release && waited < 12_000; waited += 200) {
+      await sleep(200);
+      const now = await listening();
+      if (now !== null) {
+        ready(now);
+        return 0;
+      }
+      release = acquireStartLock(dataDir);
+    }
+  }
+  const probes = io.probes ?? (await defaultProbes(io.env));
+  const store = new Store(path.join(dataDir, "pipeline.sqlite"));
+  const tried = new Set<number>();
+  let server;
+  let port = forced ? forcedPort : await pickPort(desk, io.env);
+  try {
+    for (;;) {
+      try {
+        server = await startDashboard({ store, dataDir, env: io.env, port, probes, project: desk.project, tick: (tickArgv) => runDeskTick({ store, env: io.env, argv: tickArgv }) });
+        break;
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== "EADDRINUSE") throw error;
+        if (forced || port === 0 || tried.size >= 5) {
+          io.stderr(`✗ Port ${port} is in use.\nFix: open http://127.0.0.1:${port} if it is already the dashboard, or pass --port <n>.\n`);
+          store.close();
+          release?.();
+          return 1;
+        }
+        // Lost a race for an auto-chosen port: take the next one.
+        tried.add(port);
+        port = await pickPort(desk, io.env, canListen, tried);
+      }
+    }
+  } catch (error) {
+    store.close();
+    release?.();
+    throw error;
+  }
+  const address = server.address();
+  const bound = address && typeof address === "object" ? address.port : port;
+  writeDashboardRecord(dataDir, bound, desk.project?.id ?? null);
+  release?.();
+  ready(bound);
+  const close = () =>
+    new Promise<void>((resolve, reject) => {
+      server.close((error) => (error ? reject(error) : resolve()));
+      server.closeAllConnections();
+    }).finally(() => {
+      removeDashboardRecord(dataDir, bound);
+      store.close();
+    });
+  process.once("exit", () => removeDashboardRecord(dataDir, bound));
+  if (!io.onListen) {
+    // Drop the record, then let the signal do what it would have done.
+    for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"] as const) {
+      // A persistent listener: a second signal that arrives while this one is handled must not take the default action first.
+      process.on(signal, () => {
+        removeDashboardRecord(dataDir, bound);
+        process.removeAllListeners(signal);
+        process.kill(process.pid, signal);
+      });
+    }
+  }
+  if (io.onListen) {
+    await io.onListen(bound, close);
+    return 0;
+  }
+  await new Promise(() => {});
+  return 0;
+}
+
+export async function runProductCommand(command: string, argv: string[], io: CommandIo): Promise<number> {
+  const dir = productDir(io.env);
+  if (command === "update") {
+    io.stdout(formatUpdatePlan(hasFlag(argv, "--apply")));
+    if (hasFlag(argv, "--apply")) {
+      const apply = io.apply ?? ((line: string, cwd: string) => runShell(line, io, cwd));
+      const cwd = updateInstallRoot();
+      for (const line of updateCommands()) await apply(line, cwd);
+    }
+    return 0;
+  }
+  if (command === "dev" || command === "dashboard") return runDashboard(argv, io);
+  if (command === "engine") return runEngineCommand(argv, io);
+  if (command === "scene") return runSceneCommand(argv, io);
+  if (command === "render" && flag(argv, "--scene")) return runSceneRender(argv, io);
+  if (command === "render") {
+    const config = await readProductConfig(configFile(dir), dir);
+    const requested = flag(argv, "--engine");
+    let engine;
+    try {
+      engine = chooseEngine({ command: requested, project: readProjectEngine(), machine: readMachineEngine(dataDirFor(io.env)) ?? config.defaultEngine }).engine;
+    } catch {
+      io.stderr(`✗ "${requested}" is not an engine.\nFix: choose remotion, hyperframes, vfrey-framey, or comfyui; \`npx vfrey engine list\` shows which are ready.\n`);
+      return 1;
+    }
+    let props;
+    try {
+      props = buildShort(flag(argv, "--subject") ?? "", parseComposition(flag(argv, "--composition")));
+    } catch (error) {
+      io.stderr(`${error instanceof Error ? error.message : "Render failed"}\n`);
+      return 1;
+    }
+    const probes = io.probes ?? (await defaultProbes(io.env));
+    const status = engineStatus(engine, probes);
+    const outputPath = path.resolve(flag(argv, "--output") ?? path.join(config.outputDir, `${engine.id}.mp4`));
+    let rendered;
+    try {
+      rendered = await renderChosenEngine({
+        engine,
+        availability: status.availability,
+        reason: status.reason,
+        outputPath,
+        props,
+        renderLocal: io.renderLocal ?? ((out, shortProps, id) => renderLocalFor(out, shortProps, id, io.env)),
+      });
+    } catch (error) {
+      const message = status.availability === "unavailable" ? unavailableMessage(engine, probes) : failedRender(engine, error, probes);
+      const [what, fix] = message.split(" Fix: ");
+      io.stderr(`✗ ${what}\nFix: ${fix}\n`);
+      return 1;
+    }
+    await appendInsight(insightFile(dir), {
+      engineId: engine.id,
+      engineLabel: engine.label,
+      outputPath: rendered.outputPath,
+      bytes: rendered.bytes,
+      createdAt: new Date().toISOString(),
+      subject: props.title,
+      composition: props.templateId,
+      durationSec: props.durationSec,
+    });
+    io.stdout(`${rendered.outputPath}\n`);
+    return 0;
+  }
+  if (command === "push") {
+    // No upload path exists behind this command yet. Publishing runs inside `vfrey tick`.
+    io.stderr("✗ push is not built yet.\nFix: publishing runs inside `vfrey tick` once the platform keys are set.\n");
+    return 1;
+  }
+  io.stderr(`Unknown product command ${command}\n`);
+  return 1;
+}
+
+function runShell(line: string, io: CommandIo, cwd: string): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const child = spawn(line, { shell: true, stdio: "inherit", env: io.env, cwd });
+    child.on("error", reject);
+    child.on("exit", (code) => {
+      if (code === 0) resolve();
+      else reject(new Error(`Update command failed: ${line}`));
+    });
+  });
+}
+
+function failedRender(engine: ReturnType<typeof engineById>, error: unknown, probes: EngineProbes): string {
+  return failedMessage(engine, error, probes);
+}
+
+async function renderLocalFor(
+  outputPath: string,
+  props: import("@vfrey/contracts").RenderProps,
+  engine: EngineId,
+  env: NodeJS.ProcessEnv,
+): Promise<void> {
+  const forced = forcedFailure(engine, env);
+  if (forced) throw new Error(forced);
+  if (engine === "vfrey-framey" || engine === "hyperframes") {
+    await renderHtmlEngine({ engine, props, voiceoverPath: null, outputPath, workDir: `${outputPath}.work`, env });
+    return;
+  }
+  await renderVerticalShort(outputPath, props);
+}
+
+/** `vfrey engine list` and `vfrey engine use <engine>`. */
+async function runEngineCommand(argv: string[], io: CommandIo): Promise<number> {
+  const [action, name] = argv;
+  const probes = io.probes ?? (await defaultProbes(io.env));
+  const dataDir = dataDirFor(io.env);
+  if (action === "list" || action === undefined) {
+    const current = engineById(readMachineEngine(dataDir) ?? DEFAULT_ENGINE).id;
+    const rows = allEngineStatuses(probes).map((row) => ({ ...row, default: row.id === current }));
+    if (hasFlag(argv, "--json")) {
+      io.stdout(`${JSON.stringify({ ok: true, default: current, engines: rows }, null, 2)}\n`);
+      return 0;
+    }
+    const width = Math.max(...rows.map((row) => row.id.length));
+    const lines = rows.map(
+      (row) => `${row.default ? "*" : " "} ${row.id.padEnd(width)}  ${statusText(row)}${row.default ? "  (default)" : ""}`,
+    );
+    io.stdout(`${[...lines, "", "Pick one for a run with --engine, for a series with `desk series update --engine`, or for the machine with `engine use <engine>`."].join("\n")}\n`);
+    return 0;
+  }
+  if (action === "use") {
+    if (!name || name.startsWith("--")) {
+      io.stderr("✗ engine use needs an engine.\nFix: run `npx vfrey engine use vfrey-framey` or `npx vfrey engine use remotion`.\n");
+      return 1;
+    }
+    const store = new Store(path.join(dataDir, "pipeline.sqlite"));
+    try {
+      const result = verbs.engineUse(store, { engine: name, probes });
+      if (!result.ok) {
+        io.stderr(`✗ ${result.refusal}\nFix: ${result.fix}\n`);
+        return 1;
+      }
+      io.stdout(`Default engine: ${String(result.data?.label)}\n`);
+      return 0;
+    } finally {
+      store.close();
+    }
+  }
+  io.stderr(`✗ Unknown engine command "${action}".\nFix: use \`npx vfrey engine list\` or \`npx vfrey engine use <engine>\`.\n`);
+  return 1;
+}

package/src/product/config-file.ts

@@ -0,0 +1,38 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+export interface ProductConfig {
+  outputDir: string;
+  defaultEngine: string;
+}
+
+export function defaultProductConfig(dir: string): ProductConfig {
+  return { outputDir: path.join(dir, "out"), defaultEngine: "remotion" };
+}
+
+export function parseProductConfig(raw: string, fallback: ProductConfig): ProductConfig {
+  if (!raw.trim()) return fallback;
+  const parsed = JSON.parse(raw) as Partial<ProductConfig>;
+  return {
+    outputDir: typeof parsed.outputDir === "string" && parsed.outputDir.trim() ? parsed.outputDir : fallback.outputDir,
+    defaultEngine:
+      typeof parsed.defaultEngine === "string" && parsed.defaultEngine.trim()
+        ? parsed.defaultEngine
+        : fallback.defaultEngine,
+  };
+}
+
+export async function readProductConfig(filePath: string, dir: string): Promise<ProductConfig> {
+  const fallback = defaultProductConfig(dir);
+  try {
+    return parseProductConfig(await readFile(filePath, "utf8"), fallback);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return fallback;
+    throw error;
+  }
+}
+
+export async function writeProductConfig(filePath: string, config: ProductConfig): Promise<void> {
+  await mkdir(path.dirname(filePath), { recursive: true });
+  await writeFile(filePath, `${JSON.stringify(config)}\n`);
+}

package/src/product/engine-choice.ts

@@ -0,0 +1,89 @@
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { DatabaseSync } from "node:sqlite";
+import { findProject } from "../project/discover.js";
+import {
+  DEFAULT_ENGINE,
+  ENGINES,
+  engineById,
+  engineStatus,
+  otherReadyEngine,
+  type EngineProbes,
+  type EngineSpec,
+} from "./engines.js";
+
+export type ChoiceSource = "command" | "series" | "project" | "default" | "fallback";
+
+export interface EngineChoice {
+  engine: EngineSpec;
+  source: ChoiceSource;
+}
+
+/** The most specific choice wins: the command, then the series, then the project (vfrey.json), then the machine default, then Remotion. */
+export function chooseEngine(input: { command?: string | null; series?: string | null; project?: string | null; machine?: string | null }): EngineChoice {
+  const pick = (value: string | null | undefined): EngineSpec | null => {
+    if (!value || !value.trim()) return null;
+    try {
+      return engineById(value);
+    } catch {
+      return null;
+    }
+  };
+  const command = input.command?.trim() ? engineById(input.command) : null;
+  if (command) return { engine: command, source: "command" };
+  const series = pick(input.series);
+  if (series) return { engine: series, source: "series" };
+  const project = pick(input.project);
+  if (project) return { engine: project, source: "project" };
+  const machine = pick(input.machine);
+  if (machine) return { engine: machine, source: "default" };
+  return { engine: engineById(DEFAULT_ENGINE), source: "fallback" };
+}
+
+/** The machine default, read without creating or changing the database. */
+export function readMachineEngine(dataDir: string): string | null {
+  const file = path.join(dataDir, "pipeline.sqlite");
+  if (!existsSync(file)) return null;
+  let db: DatabaseSync | null = null;
+  try {
+    db = new DatabaseSync(file, { readOnly: true });
+    const row = db.prepare(`SELECT value FROM desk_settings WHERE key = 'engine.default'`).get() as { value: string } | undefined;
+    return row?.value ?? null;
+  } catch {
+    return null;
+  } finally {
+    db?.close();
+  }
+}
+
+/** The `Fix:` text for a chosen engine that cannot render: name another ready engine, or point at doctor. */
+export function engineFix(chosen: EngineSpec, probes: EngineProbes): string {
+  const other = otherReadyEngine(chosen.id, probes);
+  return other
+    ? `render with ${other.label} instead: pass --engine ${other.id}, or run \`npx vfrey engine use ${other.id}\`, then run it again.`
+    : "run `npx vfrey doctor` to see what is missing, then run it again.";
+}
+
+/** Message for a chosen engine that is not ready. One sentence, then the fix. */
+export function unavailableMessage(chosen: EngineSpec, probes: EngineProbes): string {
+  const status = engineStatus(chosen, probes);
+  return `${chosen.label} is unavailable${status.reason ? `: ${status.reason}` : ""}. Fix: ${engineFix(chosen, probes)}`;
+}
+
+/** Message for a chosen engine that was ready and then failed. There is no fallback render. */
+export function failedMessage(chosen: EngineSpec, error: unknown, probes: EngineProbes): string {
+  const raw = (error instanceof Error ? error.message : String(error)).replace(/\s+/g, " ").trim();
+  // An error that knows its own fix keeps it.
+  const [what = raw, own] = raw.split(" Fix: ");
+  const text = what.replace(/\.$/, "").slice(0, 400);
+  return `${chosen.label} could not render the video: ${text}. Fix: ${own ?? engineFix(chosen, probes)}`;
+}
+
+export function engineIds(): string[] {
+  return ENGINES.map((engine) => engine.id);
+}
+
+/** The engine the nearest vfrey.json names, or null. A broken vfrey.json throws a ProjectError (a refusal with a Fix line). */
+export function readProjectEngine(cwd: string = process.cwd()): string | null {
+  return findProject(cwd)?.engine ?? null;
+}

package/src/product/engines.ts

@@ -0,0 +1,103 @@
+export const ENGINE_IDS = ["remotion", "hyperframes", "vfrey-framey", "comfyui"] as const;
+
+export type EngineId = (typeof ENGINE_IDS)[number];
+
+export interface EngineSpec {
+  id: EngineId;
+  label: string;
+  /** A local render needs no paid API key. */
+  localFree: boolean;
+}
+
+export const ENGINES: readonly EngineSpec[] = [
+  { id: "remotion", label: "Remotion", localFree: true },
+  { id: "hyperframes", label: "HyperFrames", localFree: true },
+  { id: "vfrey-framey", label: "vfrey Framey", localFree: true },
+  { id: "comfyui", label: "ComfyUI", localFree: true },
+];
+
+export const DEFAULT_ENGINE: EngineId = "remotion";
+
+export type EngineAvailability = "ready" | "unavailable";
+
+export interface EngineProbes {
+  /** The upstream `hyperframes` CLI answered `--version`. */
+  hyperframesCli: boolean;
+  comfyReachable: boolean;
+  /** Why the vendored Framey renderer cannot run here. Null: it can. Absent: not probed, so unavailable. */
+  frameyProblem?: string | null;
+  /** Why an HTML engine has no Chrome or ffmpeg here. Null: it has both. */
+  renderEnvProblem?: string | null;
+  /** Only the Chrome Headless Shell is missing for Framey: its first render downloads it. */
+  frameyDownloadsChrome?: boolean;
+}
+
+export interface EngineStatus {
+  id: EngineId;
+  label: string;
+  availability: EngineAvailability;
+  /** Why the engine cannot render. Null when it is ready. */
+  reason: string | null;
+  /** A caveat on a ready engine, such as a first-render download. Null when there is none. */
+  note: string | null;
+}
+
+export const FRAMEY_DOWNLOAD_NOTE = "downloads Chrome Headless Shell on first render";
+
+/** `ready`, `ready (note)`, or `unavailable: reason`. */
+export function statusText(row: Pick<EngineStatus, "availability" | "reason" | "note">): string {
+  if (row.availability === "ready") return row.note ? `ready (${row.note})` : "ready";
+  return `unavailable: ${row.reason}`;
+}
+
+export function engineById(value: string): EngineSpec {
+  const needle = value.trim().toLowerCase();
+  const found = ENGINES.find((engine) => engine.id === needle || engine.label.toLowerCase() === needle);
+  if (!found) {
+    throw new Error("Unknown engine. Choose remotion, hyperframes, vfrey-framey, or comfyui.");
+  }
+  return found;
+}
+
+export const HYPERFRAMES_MISSING = "HyperFrames CLI not found; install it or choose vfrey Framey";
+export const COMFYUI_REASON = "needs a ComfyUI server at COMFYUI_URL; not wired yet";
+
+export function engineStatus(engine: EngineSpec, probes: EngineProbes): EngineStatus {
+  const base = { id: engine.id, label: engine.label };
+  const ready: EngineStatus = { ...base, availability: "ready", reason: null, note: null };
+  const no = (reason: string): EngineStatus => ({ ...base, availability: "unavailable", reason, note: null });
+  switch (engine.id) {
+    case "remotion":
+      return ready;
+    case "vfrey-framey":
+      if (probes.frameyProblem === undefined) return no("the Framey renderer was not probed on this machine");
+      if (probes.frameyProblem) return no(probes.frameyProblem);
+      return probes.frameyDownloadsChrome ? { ...ready, note: FRAMEY_DOWNLOAD_NOTE } : ready;
+    case "hyperframes":
+      if (!probes.hyperframesCli) return no(HYPERFRAMES_MISSING);
+      return probes.renderEnvProblem ? no(probes.renderEnvProblem) : ready;
+    default:
+      // A server answering does not make a renderer. ComfyUI is the next slice.
+      return no(COMFYUI_REASON);
+  }
+}
+
+export function allEngineStatuses(probes: EngineProbes): EngineStatus[] {
+  return ENGINES.map((engine) => engineStatus(engine, probes));
+}
+
+export function availabilityFor(engine: EngineSpec, probes: EngineProbes): EngineAvailability {
+  return engineStatus(engine, probes).availability;
+}
+
+/** The first ready engine other than `chosen`, Remotion first. */
+export function otherReadyEngine(chosen: EngineId, probes: EngineProbes): EngineSpec | null {
+  const order = [ENGINES[0]!, ...ENGINES.filter((engine) => engine.id !== "remotion")];
+  return order.find((engine) => engine.id !== chosen && availabilityFor(engine, probes) === "ready") ?? null;
+}
+
+export function assertCanRender(engine: EngineSpec, availability: EngineAvailability, reason?: string | null): void {
+  if (availability === "unavailable") {
+    throw new Error(`${engine.label} is unavailable on this machine${reason ? `: ${reason}` : ""}.`);
+  }
+}

package/src/product/insights.ts

@@ -0,0 +1,50 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+export interface InsightRow {
+  engineId: string;
+  engineLabel: string;
+  outputPath: string;
+  bytes: number;
+  createdAt: string;
+  subject?: string;
+  composition?: string;
+  durationSec?: number;
+}
+
+export function summarizeInsights(rows: InsightRow[]): { count: number; bytes: number; byEngine: Record<string, number> } {
+  const byEngine: Record<string, number> = {};
+  let bytes = 0;
+  for (const row of rows) {
+    bytes += row.bytes;
+    byEngine[row.engineLabel] = (byEngine[row.engineLabel] ?? 0) + 1;
+  }
+  return { count: rows.length, bytes, byEngine };
+}
+
+export function parseInsights(raw: string): InsightRow[] {
+  if (!raw.trim()) return [];
+  const parsed = JSON.parse(raw) as unknown;
+  if (!Array.isArray(parsed)) return [];
+  return parsed.filter((row): row is InsightRow => {
+    if (!row || typeof row !== "object") return false;
+    const item = row as InsightRow;
+    return typeof item.engineId === "string" && typeof item.outputPath === "string" && typeof item.bytes === "number";
+  });
+}
+
+export async function readInsights(filePath: string): Promise<InsightRow[]> {
+  try {
+    return parseInsights(await readFile(filePath, "utf8"));
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return [];
+    throw error;
+  }
+}
+
+export async function appendInsight(filePath: string, row: InsightRow): Promise<InsightRow[]> {
+  const rows = [...(await readInsights(filePath)), row];
+  await mkdir(path.dirname(filePath), { recursive: true });
+  await writeFile(filePath, `${JSON.stringify(rows)}\n`);
+  return rows;
+}