@crievo/omni 0.0.0-stage → 0.1.1

package/tools/lib/fanout.mjs

@@ -0,0 +1,234 @@
+/* ============================================================================
+   Fan-out: one fork per scene for a stage (composition, wireframes, narration),
+   and the guard that makes the same scene impossible to run twice at once.
+
+   On 2026-10-17 the composition of 2026-10-16-https-x-ai-news-grok ran twice:
+   the orchestrator launched the 8 scene forks and an av-motion fork launched
+   another 8, for the same scenes, writing the same files (~US$ 11 lost). Prompt
+   rules alone don't stop that; this file does, by construction:
+
+   - `plan` hands each scene out once. A scene already handed out (planned or
+     running, and younger than the TTL) is listed as busy and not handed out
+     again: a second `plan`, from whoever, has nothing to launch.
+   - a fork starts with `claim`: the scene must be in the fork's run and not
+     started yet. A second fork with the same prompt, or one from another run,
+     is refused (exit 3) and stops before writing anything.
+   - `done` closes the scene; `release` frees a scene whose fork died, so the
+     orchestrator can hand it out again.
+
+   State: videos/<slug>/.fanout/<kind>.json, one item per scene:
+     { "c03": { "run": "r-k2f9", "state": "planned"|"started"|"done", "at": ISO, "started_at"?: ISO } }
+
+   `withScenesLock` is the lock every parallel writer of scenes.json takes
+   (`compose.mjs apply`, `narrate.mjs apply`).
+   ============================================================================ */
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync, rmSync, renameSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { randomBytes } from "node:crypto";
+
+export const KINDS = ["compose", "wireframe", "narration"];
+export const DEFAULT_TTL_MIN = 45;
+
+export class FanoutError extends Error {
+  constructor(msg, code = 3) {
+    super(msg);
+    this.code = code;
+  }
+}
+
+const stateFile = (dir, kind) => join(dir, ".fanout", `${kind}.json`);
+
+function checkKind(kind) {
+  if (!KINDS.includes(kind)) throw new FanoutError(`tipo desconhecido: ${kind} (${KINDS.join(", ")})`, 2);
+}
+
+function read(dir, kind) {
+  try {
+    return JSON.parse(readFileSync(stateFile(dir, kind), "utf8"));
+  } catch {
+    return {};
+  }
+}
+
+function write(dir, kind, items) {
+  mkdirSync(join(dir, ".fanout"), { recursive: true });
+  const file = stateFile(dir, kind);
+  const tmp = `${file}.${process.pid}.tmp`;
+  writeFileSync(tmp, JSON.stringify(items, null, 2) + "\n");
+  renameSync(tmp, file);
+}
+
+/* a lock directory: mkdir is atomic. One left by a call that died is stale after 60 s */
+async function withLock(path, fn, { waitMs = 30_000, staleMs = 60_000 } = {}) {
+  const until = Date.now() + waitMs;
+  for (;;) {
+    try {
+      mkdirSync(path);
+      break;
+    } catch {
+      try {
+        if (Date.now() - statSync(path).mtimeMs > staleMs) rmSync(path, { recursive: true, force: true });
+      } catch {}
+      if (Date.now() > until) throw new FanoutError(`lock ocupado há mais de ${waitMs / 1000} s: ${path}`, 1);
+      await new Promise(r => setTimeout(r, 100));
+    }
+  }
+  try {
+    return await fn();
+  } finally {
+    rmSync(path, { recursive: true, force: true });
+  }
+}
+
+export const withScenesLock = (dir, fn) => withLock(join(dir, ".scenes.lock"), fn);
+const withStateLock = (dir, fn) => withLock(join(dir, ".fanout.lock"), fn);
+
+const ageMin = (iso, now) => (now - Date.parse(iso)) / 60_000;
+
+/* planned or started, and younger than the TTL: someone holds the scene */
+function holding(item, now, ttlMin) {
+  return item && item.state !== "done" && ageMin(item.started_at ?? item.at, now) < ttlMin;
+}
+
+const newRun = prefix => `${prefix}-${randomBytes(3).toString("hex")}`;
+
+/**
+ * Hands each scene out once. Returns the new run (null when nothing was handed
+ * out), the scenes in it and the ones someone else still holds.
+ * @param {string} dir video folder
+ * @param {string} kind
+ * @param {string[]} ids scenes to hand out
+ */
+export async function plan(dir, kind, ids, { ttlMin = DEFAULT_TTL_MIN, now = Date.now() } = {}) {
+  checkKind(kind);
+  return withStateLock(dir, () => {
+    const items = read(dir, kind);
+    const run = newRun("r");
+    const planned = [],
+      busy = [];
+    for (const id of ids) {
+      const it = items[id];
+      if (holding(it, now, ttlMin))
+        busy.push({ id, run: it.run, state: it.state, age_min: Math.round(ageMin(it.started_at ?? it.at, now)) });
+      else {
+        items[id] = { run, state: "planned", at: new Date(now).toISOString() };
+        planned.push(id);
+      }
+    }
+    if (planned.length) write(dir, kind, items);
+    return { run: planned.length ? run : null, planned, busy };
+  });
+}
+
+/**
+ * A fork takes its scene before writing anything. With `run`, the scene must be
+ * planned in that run and not started; without it (a scene call made alone), the
+ * scene must be free, and a run of its own is created.
+ */
+export async function claim(dir, kind, id, run, { ttlMin = DEFAULT_TTL_MIN, now = Date.now() } = {}) {
+  checkKind(kind);
+  return withStateLock(dir, () => {
+    const items = read(dir, kind);
+    const it = items[id];
+    const at = new Date(now).toISOString();
+    if (!run) {
+      if (holding(it, now, ttlMin))
+        throw new FanoutError(
+          `${id} já está em ${it.state === "started" ? "andamento" : "fila"} na rodada ${it.run} ` +
+            `(há ${Math.round(ageMin(it.started_at ?? it.at, now))} min): não rode de novo`,
+        );
+      const solo = newRun("s");
+      items[id] = { run: solo, state: "started", at, started_at: at };
+      write(dir, kind, items);
+      return solo;
+    }
+    if (!it || it.run !== run)
+      throw new FanoutError(
+        it && holding(it, now, ttlMin)
+          ? `${id} pertence à rodada ${it.run}, não à ${run}: outro fork cuida dela. Pare sem escrever nada`
+          : `${id} não foi distribuída na rodada ${run}: pare sem escrever nada`,
+      );
+    if (it.state === "started")
+      throw new FanoutError(`${id} já foi iniciada por outro fork da rodada ${run}: pare sem escrever nada`);
+    if (it.state === "done") throw new FanoutError(`${id} já foi concluída na rodada ${run}`);
+    if (!holding(it, now, ttlMin)) throw new FanoutError(`a rodada ${run} de ${id} expirou: rode o plan de novo`);
+    items[id] = { ...it, state: "started", started_at: at };
+    write(dir, kind, items);
+    return run;
+  });
+}
+
+/** The fork finished its scene (with or without success: the stage's gate says the rest). */
+export async function done(dir, kind, id, run, { now = Date.now() } = {}) {
+  checkKind(kind);
+  return withStateLock(dir, () => {
+    const items = read(dir, kind);
+    const it = items[id];
+    if (!it || it.run !== run) throw new FanoutError(`${id} não está na rodada ${run}`, 1);
+    items[id] = { ...it, state: "done", done_at: new Date(now).toISOString() };
+    write(dir, kind, items);
+  });
+}
+
+/** Frees scenes whose fork died (error, no report), so `plan` hands them out again. */
+export async function release(dir, kind, ids) {
+  checkKind(kind);
+  return withStateLock(dir, () => {
+    const items = read(dir, kind);
+    const freed = ids.filter(id => items[id] && items[id].state !== "done");
+    for (const id of freed) delete items[id];
+    write(dir, kind, items);
+    return freed;
+  });
+}
+
+/** Who holds what right now: scenes planned or running, younger than the TTL. */
+export function busy(dir, kind, { ttlMin = DEFAULT_TTL_MIN, now = Date.now() } = {}) {
+  checkKind(kind);
+  const items = read(dir, kind);
+  return Object.entries(items)
+    .filter(([, it]) => holding(it, now, ttlMin))
+    .map(([id, it]) => ({
+      id,
+      run: it.run,
+      state: it.state,
+      age_min: Math.round(ageMin(it.started_at ?? it.at, now)),
+    }));
+}
+
+export const hasState = (dir, kind) => existsSync(stateFile(dir, kind));
+
+/** The Agent tool takes an alias; the config may hold a full id */
+export function agentModel(model) {
+  return ["fable", "opus", "sonnet", "haiku"].find(a => String(model).includes(a)) ?? "opus";
+}
+
+/**
+ * Splits ids into waves of at most `parallel`.
+ * @param {string[]} ids
+ */
+export function waves(ids, parallel) {
+  const out = [];
+  for (let i = 0; i < ids.length; i += parallel) out.push(ids.slice(i, i + parallel));
+  return out;
+}
+
+/** The lines a `plan` prints for the orchestrator: waves, Agent parameters and each prompt. */
+export function printPlan({ title, run, waves: ws, model, effort, prompt, busy: held, after }) {
+  console.log(title);
+  if (held.length)
+    console.log(
+      `em andamento (não lance de novo): ${held.map(b => `${b.id} (rodada ${b.run}, ${b.state === "started" ? "rodando" : "na fila"} há ${b.age_min} min)`).join(", ")}`,
+    );
+  if (!run) return;
+  console.log(`rodada: ${run}`);
+  ws.forEach((w, i) => console.log(`onda ${i + 1}: ${w.join(" ")}`));
+  console.log(
+    `\nCada onda é UMA mensagem com uma chamada Agent por cena (subagent_type general-purpose, ` +
+      `model ${model}, effort ${effort}, em primeiro plano); a próxima onda só depois de todos os relatórios. ` +
+      `Este plan não se repete: rodar de novo não distribui o que já está nesta rodada. Prompts:`,
+  );
+  for (const w of ws) for (const id of w) console.log(`  ${id}: ${prompt(id)}`);
+  if (after) console.log(`\n${after}`);
+}

package/tools/lib/http.mjs

@@ -0,0 +1,94 @@
+/* ============================================================================
+   HTTP shared by every platform client: one request with the platforms'
+   readable error. Pure: `fetch` is injected (defaults to the global one), so
+   the same code runs on the CLI, in a cloud function and in tests.
+   ============================================================================ */
+
+/**
+ * @typedef {typeof globalThis.fetch} Fetch
+ * @typedef {Error & { code?: string | null, status?: number }} PlatformError
+ * @typedef {{ r: Response, j: any, text: string }} HttpResult
+ */
+
+/**
+ * One HTTP call. On a non-2xx answer throws `label: <status> <message>` with
+ * `code` (the platform's error code, when there is one) and `status`.
+ * @param {string} url
+ * @param {RequestInit} [opts]
+ * @param {string} [label]
+ * @param {{ fetch?: Fetch }} [deps]
+ * @returns {Promise<HttpResult>}
+ */
+export async function request(url, opts, label, { fetch: f = globalThis.fetch } = {}) {
+  const r = await f(url, opts);
+  const text = await r.text();
+  let j = null;
+  try {
+    j = JSON.parse(text);
+  } catch {
+    /* not JSON */
+  }
+  if (!r.ok) {
+    const e = j?.error;
+    const msg =
+      e?.error_user_msg ??
+      e?.message ??
+      j?.error_description ??
+      (typeof e === "string" ? e : null) ??
+      text.slice(0, 400);
+    /* the code says more than the message (TikTok's is sometimes just "read the guidelines") */
+    const code = typeof e === "object" && e?.code != null && e.code !== "ok" ? String(e.code) : null;
+    /** @type {PlatformError} */
+    const error = new Error(`${label}: ${r.status} ${msg}${code && !String(msg).includes(code) ? ` (${code})` : ""}`);
+    error.code = code;
+    error.status = r.status;
+    throw error;
+  }
+  return { r, j, text };
+}
+
+/**
+ * @param {number} ms
+ * @returns {Promise<void>}
+ */
+export const sleep = ms => new Promise(ok => setTimeout(ok, ms));
+
+/** One day in ms. */
+export const DAY = 86_400_000;
+/** One hour in ms. */
+export const HOUR = 3_600_000;
+
+/**
+ * Deps every core function accepts. All optional: the defaults are the real ones.
+ * @typedef {object} Deps
+ * @property {Fetch} [fetch]
+ * @property {() => number} [now] epoch ms
+ * @property {(ms: number) => Promise<void>} [sleep]
+ * @property {(line: string) => void} [log] stdout-like progress
+ * @property {(line: string) => void} [warn] stderr-like warnings
+ * @property {() => number} [random] in [0, 1)
+ */
+
+/**
+ * Fills the missing deps with the real ones.
+ * @param {Deps} [deps]
+ * @returns {Required<Deps>}
+ */
+export function withDefaults(deps = {}) {
+  return {
+    fetch: deps.fetch ?? globalThis.fetch,
+    now: deps.now ?? Date.now,
+    sleep: deps.sleep ?? sleep,
+    log: deps.log ?? (() => {}),
+    warn: deps.warn ?? (() => {}),
+    random: deps.random ?? Math.random,
+  };
+}
+
+/**
+ * Token storage: where the platform tokens live (the .env on the CLI, a secret
+ * store in the cloud). `get` returns "" when missing.
+ * @typedef {object} TokenStore
+ * @property {(name: string) => string} get
+ * @property {(values: Record<string, string>) => void | Promise<void>} set
+ */

package/tools/lib/index.js

@@ -0,0 +1,14 @@
+/* Entry for `node --test tools/lib`: node resolves the folder to this file, which loads every
+ *.test.mjs below it into the same test run. Not a library entry point: import the modules directly. */
+const { readdirSync } = require("node:fs");
+const { join } = require("node:path");
+const { pathToFileURL } = require("node:url");
+
+const walk = dir =>
+  readdirSync(dir, { withFileTypes: true }).flatMap(e =>
+    e.isDirectory() ? walk(join(dir, e.name)) : e.name.endsWith(".test.mjs") ? [join(dir, e.name)] : [],
+  );
+
+(async () => {
+  for (const file of walk(__dirname).sort()) await import(pathToFileURL(file).href);
+})();

package/tools/lib/mcp-server.mjs

@@ -0,0 +1,69 @@
+/* A minimal MCP server over stdio (JSON-RPC 2.0, one message per line), enough for the plugin's tools:
+   initialize, tools/list, tools/call and ping. The `omni mcp` command serves its tools with it
+   (docs/specs/phase-2-plugin-cli.md, step 4); no SDK, so the CLI carries no extra dependency.
+
+   A tool is { name, description, inputSchema, run(args) → string }; its text goes back as the result, and
+   a thrown Error goes back as a tool error the model can read. */
+
+import { createInterface } from "node:readline";
+
+const PROTOCOL = "2025-06-18";
+
+/**
+ * @typedef {{ name: string, description: string, inputSchema: object, run: (args: any) => Promise<string> | string }} Tool
+ * @param {{ name: string, version: string, tools: Tool[], input?: NodeJS.ReadableStream, output?: NodeJS.WritableStream }} o
+ * @returns {Promise<void>} resolves when the input ends
+ */
+export function serveMcp({ name, version, tools, input = process.stdin, output = process.stdout }) {
+  const send = (/** @type {unknown} */ msg) => output.write(`${JSON.stringify(msg)}\n`);
+  const reply = (/** @type {unknown} */ id, /** @type {unknown} */ result) => send({ jsonrpc: "2.0", id, result });
+  const error = (/** @type {unknown} */ id, /** @type {number} */ code, /** @type {string} */ message) =>
+    send({ jsonrpc: "2.0", id, error: { code, message } });
+
+  /** @param {any} msg */
+  async function handle(msg) {
+    const { id, method, params } = msg ?? {};
+    const isRequest = id !== undefined && id !== null;
+    if (method === "initialize")
+      return reply(id, {
+        protocolVersion: params?.protocolVersion ?? PROTOCOL,
+        capabilities: { tools: {} },
+        serverInfo: { name, version },
+      });
+    if (method === "ping") return reply(id, {});
+    if (method === "tools/list")
+      return reply(id, {
+        tools: tools.map(({ name: n, description, inputSchema }) => ({ name: n, description, inputSchema })),
+      });
+    if (method === "tools/call") {
+      const tool = tools.find(t => t.name === params?.name);
+      if (!tool) return error(id, -32602, `ferramenta desconhecida: ${params?.name}`);
+      try {
+        const text = await tool.run(params?.arguments ?? {});
+        return reply(id, { content: [{ type: "text", text: String(text) }] });
+      } catch (e) {
+        return reply(id, {
+          content: [{ type: "text", text: String(/** @type {Error} */ (e).message) }],
+          isError: true,
+        });
+      }
+    }
+    /* notifications (initialized, cancelled…) need no answer */
+    if (isRequest) error(id, -32601, `método não suportado: ${method}`);
+  }
+
+  return new Promise(resolve => {
+    const rl = createInterface({ input });
+    rl.on("line", line => {
+      if (!line.trim()) return;
+      let msg;
+      try {
+        msg = JSON.parse(line);
+      } catch {
+        return error(null, -32700, "JSON inválido");
+      }
+      void handle(msg);
+    });
+    rl.on("close", () => resolve());
+  });
+}

package/tools/lib/metrics/metrics.mjs

@@ -0,0 +1,204 @@
+/* ============================================================================
+   Reel metrics: what is due at a given age (the age milestones and the
+   periodic reading), the snapshot shape, and the collection of one video and
+   of the account. Pure: the record comes in and goes out; the caller reads
+   and writes metrics.json / account.json. Read only on Instagram.
+   ============================================================================ */
+
+import { HOUR, withDefaults } from "../http.mjs";
+
+/** @typedef {import("../http.mjs").Deps} Deps */
+/** @typedef {import("../platforms/instagram.mjs").InstagramClient} InstagramClient */
+
+/** Every how many hours the collector runs. */
+export const AGENT_STEP_H = 4;
+
+/** The age milestones: [name, hours]. */
+export const MILESTONES = /** @type {const} */ ([
+  ["1h", 1],
+  ["3h", 3],
+  ["24h", 24],
+  ["72h", 72],
+  ["7d", 168],
+  ["30d", 720],
+]);
+
+/**
+ * How often the Reel is read, by its age (hours): every step in the first 30 days, then daily.
+ * @param {number} ageH
+ */
+export const currentInterval = ageH => (ageH < 720 ? AGENT_STEP_H : 24);
+
+export const BASE = ["views", "reach", "likes", "comments", "saved", "shares", "total_interactions"];
+export const REEL = ["ig_reels_avg_watch_time", "ig_reels_video_view_total_time", "reels_skip_rate"];
+
+/**
+ * @typedef {object} Snapshot
+ * @property {string} at
+ * @property {number} age_h
+ * @property {number | null} views
+ * @property {number | null} reach
+ * @property {number | null} likes
+ * @property {number | null} comments
+ * @property {number | null} saves
+ * @property {number | null} shares
+ * @property {number | null} interactions
+ * @property {number | null} avg_watch_s
+ * @property {number | null} watched_pct
+ * @property {number | null} skip_3s_pct
+ * @property {number | null} total_watch_h
+ */
+
+/**
+ * @typedef {object} VideoRecord metrics.json `instagram`
+ * @property {string} id
+ * @property {string} published_at
+ * @property {number | null} [duration_s]
+ * @property {Array<Snapshot & { milestone: string }>} snapshots
+ * @property {Snapshot[]} [hourly]
+ * @property {Snapshot} [current]
+ * @property {{ at: string, message: string } | null} [error]
+ * @property {boolean} [removed]
+ */
+
+/**
+ * One reading from the raw insights.
+ * @param {Record<string, any>} m raw metrics by name
+ * @param {number | null | undefined} duration seconds of the uploaded MP4
+ * @param {number} ageH
+ * @param {string} at ISO
+ * @returns {Snapshot}
+ */
+export function snapshot(m, duration, ageH, at) {
+  const avg = m.ig_reels_avg_watch_time != null ? Math.round(m.ig_reels_avg_watch_time / 100) / 10 : null;
+  return {
+    at,
+    age_h: Math.round(ageH * 10) / 10,
+    views: m.views ?? null,
+    reach: m.reach ?? null,
+    likes: m.likes ?? null,
+    comments: m.comments ?? null,
+    saves: m.saved ?? null,
+    shares: m.shares ?? null,
+    interactions: m.total_interactions ?? null,
+    avg_watch_s: avg,
+    watched_pct: avg != null && duration ? Math.round((avg / duration) * 1000) / 10 : null,
+    skip_3s_pct: m.reels_skip_rate ?? null,
+    total_watch_h:
+      m.ig_reels_video_view_total_time != null ? Math.round((m.ig_reels_video_view_total_time / HOUR) * 10) / 10 : null,
+  };
+}
+
+/**
+ * What is due now: the milestones in their window and the current reading if due.
+ * A milestone is only taken near its age (up to half a milestone later, at least 1 h):
+ * a late snapshot would be skewed, so a missed window stays missed.
+ * @param {{ snapshots?: Array<{ milestone: string }>, current?: { at: string } }} rec
+ * @param {number} ageH
+ * @param {boolean} force
+ * @param {number} now epoch ms
+ * @returns {{ milestones: string[], current: boolean }}
+ */
+export function due(rec, ageH, force, now) {
+  const taken = new Set((rec.snapshots ?? []).map(f => f.milestone));
+  const milestones = MILESTONES.filter(
+    ([name, h]) => !taken.has(name) && ageH >= h && ageH <= h + Math.max(1, h / 2),
+  ).map(([name]) => name);
+  const step = currentInterval(ageH);
+  const last = rec.current ? Date.parse(rec.current.at) : 0;
+  const current = force || now - last >= step * HOUR * 0.95;
+  return { milestones, current };
+}
+
+/**
+ * A media's insights; a post that is not a Reel lacks the Reel metrics (the whole call would fail).
+ * @param {InstagramClient} client @param {string} id
+ */
+export async function reelInsights(client, id) {
+  try {
+    return await client.insights(id, [...BASE, ...REEL]);
+  } catch (e) {
+    const err = /** @type {import("../http.mjs").PlatformError} */ (e);
+    if (err.status === 400 && /metric/i.test(err.message)) return client.insights(id, BASE);
+    throw e;
+  }
+}
+
+/**
+ * Collects one video if something is due.
+ * @param {{ client: InstagramClient, ig: { id: string, published_at: string }, stored?: VideoRecord | null,
+ *   duration: () => number | null, force: boolean, retryRemoved?: boolean } & Deps} p
+ *   `stored` is metrics.json's `instagram`; `duration` is only called when the record has none
+ * @returns {Promise<null | { rec: VideoRecord, milestones: string[], error: string | null }>}
+ *   null when nothing was due (nothing to write)
+ */
+export async function collectVideo({ client, ig, stored, duration, force, retryRemoved = force, ...deps }) {
+  const d = withDefaults(deps);
+  /* Reel republished: another id, another count */
+  /** @type {VideoRecord} */
+  const rec = stored?.id === ig.id ? stored : { id: ig.id, published_at: ig.published_at, snapshots: [] };
+  if (rec.removed && !retryRemoved) return null;
+  const ageH = (d.now() - Date.parse(ig.published_at)) / HOUR;
+  const { milestones, current } = due(rec, ageH, force, d.now());
+  if (!milestones.length && !current) return null;
+  rec.duration_s ??= duration();
+  try {
+    const f = snapshot(await reelInsights(client, ig.id), rec.duration_s, ageH, new Date(d.now()).toISOString());
+    for (const milestone of milestones) rec.snapshots.push({ milestone, ...f });
+    rec.hourly = [...(rec.hourly ?? []), f];
+    rec.current = f;
+    rec.error = null;
+  } catch (e) {
+    const err = /** @type {import("../http.mjs").PlatformError} */ (e);
+    rec.error = { at: new Date(d.now()).toISOString(), message: err.message };
+    /* the Reel was deleted: stop asking (collect with the video named tries again) */
+    if (err.status === 400 && /does not exist|cannot be loaded|nonexisting/i.test(err.message)) rec.removed = true;
+  }
+  return { rec, milestones, error: rec.error?.message ?? null };
+}
+
+/**
+ * @typedef {object} AccountRecord .metrics/account.json
+ * @property {Array<{ day: string, at: string, username: string, followers: number | null, following: number | null,
+ *   posts: number | null, profile_visits_day: number | null }>} snapshots
+ * @property {Array<{ at: string, followers: number | null, profile_visits_day: number | null }>} [hourly]
+ */
+
+/**
+ * The account: one snapshot per day, redone every pass (today's is the newest),
+ * and every reading in `hourly`.
+ * @param {{ client: InstagramClient, stored?: AccountRecord | null, force: boolean, day?: (now: number) => string } & Deps} p
+ *   `day` is the calendar day of a time (the runtime's local day by default)
+ * @returns {Promise<AccountRecord | null>} null when nothing was due
+ */
+export async function collectAccount({ client, stored, force, day, ...deps }) {
+  const d = withDefaults(deps);
+  const account = stored ?? { snapshots: [] };
+  const today = (day ?? (t => new Date(t).toLocaleDateString("sv-SE")))(d.now());
+  const last = account.snapshots.at(-1);
+  if (!force && last?.day === today && d.now() - Date.parse(last.at) < HOUR * 0.95) return null;
+  const me = await client.account("username,followers_count,follows_count,media_count");
+  let visits = null;
+  try {
+    visits = await client.profileVisits();
+  } catch {
+    /* small account or no permission: goes without */
+  }
+  const f = {
+    day: today,
+    at: new Date(d.now()).toISOString(),
+    username: me.username,
+    followers: me.followers_count ?? null,
+    following: me.follows_count ?? null,
+    posts: me.media_count ?? null,
+    profile_visits_day: visits,
+  };
+  if (account.snapshots.at(-1)?.day === today) account.snapshots[account.snapshots.length - 1] = f;
+  else account.snapshots.push(f);
+  /* every reading also goes into hourly: the followers curve comes from it */
+  account.hourly = [
+    ...(account.hourly ?? []),
+    { at: f.at, followers: f.followers, profile_visits_day: f.profile_visits_day },
+  ];
+  return account;
+}

package/tools/lib/narration.mjs

@@ -0,0 +1,15 @@
+/* "Sem narração e voz": content.json `narration: false`. The video has no spoken script, narration, voice or
+   captions; scenes.json holds beats with `t` and a `min_duration` per scene, and the assembly is picture,
+   effects and the bed. Absent means narrated. `omnivideo.py narrated()` reads the same flag. */
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+/** @param {string} videoDir */
+export function isNarrated(videoDir) {
+  try {
+    return JSON.parse(readFileSync(join(videoDir, "content.json"), "utf8")).narration !== false;
+  } catch {
+    return true;
+  }
+}