@crievo/omni 0.0.0-stage → 0.1.1

package/studio/api/services/sound.ts

@@ -0,0 +1,311 @@
+/* Sound timeline: the effects of beats and transitions and the bed, edited from the
+   UI. Each change is planned by tools/sound.mjs itself (volume relative to the
+   voice, ducking, trim, stretch, pitch) in a draft outside the video dir, and the
+   UI plays the ready WAVs over the voice: what you hear is what assemble
+   mixes. Saving writes to scenes.json; the export only changes on reassembly. */
+
+import { existsSync, mkdirSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { join, resolve, sep, basename } from "node:path";
+import { ROOT, NODE, TOOLS_DIR, readJson } from "./root";
+import { loadVideo, beatTime } from "../../../tools/timing.mjs";
+import {
+  planSound,
+  applyDraft,
+  applyClips,
+  soundCatalog,
+  sanitizeSound,
+  sanitizeBed,
+  sanitizeSpeed,
+  finalClock,
+  kitDir,
+} from "../../../tools/sound.mjs";
+import { videoClips, lineClips, lineDuration } from "../../../tools/soundtrack.mjs";
+import { normalizeCuts } from "../../../tools/cuts.mjs";
+import { chatWith } from "./create";
+import type { ApiResult } from "./sessions";
+
+type Result = { ok: true; output: string } | { ok: false; error: string };
+const DRAFT_DIR = join(ROOT, ".sound-draft");
+
+const normalizeSound = (s: any) => (typeof s === "string" ? { name: s } : { ...s });
+const asList = (sound: any) => (sound == null ? [] : (Array.isArray(sound) ? sound : [sound]).map(normalizeSound));
+
+/* the export's base MP4 (without the speed), for the timeline picture, and the cuts it already has */
+function baseExport(
+  dir: string,
+): { rel: string; cuts: { from: number; to: number }[]; scene_clips: Record<string, unknown> } | null {
+  const m = readJson<any>(join(dir, "export", "assembly.json"));
+  const rel = m?.base_mp4 ?? m?.mp4;
+  return rel && existsSync(join(dir, rel)) ? { rel, cuts: m.cuts ?? [], scene_clips: m.scene_clips ?? {} } : null;
+}
+
+/* the export at the chosen speed (assembly.json `mp4` when it isn't the base): once it matches the
+   edit, the editor plays it instead of the base, so what plays there is what goes out */
+function spedExport(dir: string): { path: string; mtime: number; speed: number } | null {
+  const m = readJson<any>(join(dir, "export", "assembly.json"));
+  const speed = Number(m?.speed);
+  if (!m?.base_mp4 || !m.mp4 || m.mp4 === m.base_mp4 || !(speed > 1) || !existsSync(join(dir, m.mp4))) return null;
+  return { path: m.mp4, mtime: Math.round(statSync(join(dir, m.mp4)).mtimeMs), speed };
+}
+
+export function getSoundData(dir: string) {
+  const video = loadVideo(dir);
+  /* each place's instant is in voice time (without the scene clips): the UI maps it onto the animation piece */
+  const places: any[] = [];
+  video.scenes.forEach((c: any, i: number) => {
+    if (i > 0)
+      places.push({
+        type: "transition",
+        scene: c.id,
+        element: "transition",
+        instant: +c.start.toFixed(3),
+        sounds: asList(typeof c.transition === "object" ? c.transition?.sound : null),
+      });
+    for (const b of c.beats ?? []) {
+      let instant: number | null = null,
+        error: string | null = null;
+      try {
+        instant = +(c.start + beatTime(c, b)).toFixed(3);
+      } catch (e: any) {
+        error = e.message;
+      }
+      places.push({ type: "beat", scene: c.id, element: b.element, instant, error, sounds: asList(b.sound) });
+    }
+  });
+  const exp = baseExport(dir);
+  return {
+    total: video.total_duration,
+    provisional: video.provisional,
+    format: video.format,
+    scenes: video.scenes.map((c: any) => {
+      const mp4 = c.mp4 ?? `motion/${c.id}.mp4`;
+      return {
+        id: c.id,
+        title: c.title ?? null,
+        start: c.start,
+        duration: c.duration,
+        clips: videoClips(c),
+        mp4: existsSync(join(dir, mp4)) ? { path: mp4, mtime: Math.round(statSync(join(dir, mp4)).mtimeMs) } : null,
+      };
+    }),
+    lines: video.scenes.flatMap((c: any) =>
+      (c.lines ?? []).map((l: any) => ({
+        id: l.id,
+        scene: c.id,
+        start: +(c.start + l.start).toFixed(3),
+        end: +(c.start + l.end).toFixed(3),
+        dur: lineDuration(l),
+        clips: lineClips(l),
+        wav: l.wav && existsSync(join(dir, l.wav)) ? l.wav : null,
+        text: l.text,
+      })),
+    ),
+    places,
+    bed: video.bed ? normalizeSound(video.bed) : null,
+    /* editor area cuts, in scenes.json time (tools/cuts.mjs) */
+    cuts: normalizeCuts(video.cuts, video.total_duration, video.format.fps),
+    /* the export speed (1 to 1.5); a video that never chose one in the editor keeps the one the old
+       export panel left in assembly.json */
+    speed: sanitizeSpeed(video.speed ?? readJson<any>(join(dir, "export", "assembly.json"))?.speed),
+    catalog: soundCatalog(dir),
+    export: exp
+      ? {
+          path: exp.rel,
+          mtime: Math.round(statSync(join(dir, exp.rel)).mtimeMs),
+          cuts: exp.cuts,
+          scene_clips: exp.scene_clips,
+        }
+      : null,
+    speed_export: spedExport(dir),
+    /* scenes.json changed after the export (the timeline save, or another stage): needs reassembly */
+    export_outdated: !exp || statSync(join(dir, "scenes.json")).mtimeMs > statSync(join(dir, exp.rel)).mtimeMs,
+  };
+}
+
+/* one draft per request, in a new dir; those before the previous one are removed (the UI
+   may still be downloading the previous one's WAVs) */
+let counter = 0;
+function draftDir(slug: string) {
+  const base = join(DRAFT_DIR, slug);
+  mkdirSync(base, { recursive: true });
+  const n = `${Date.now()}-${++counter}`;
+  const old = readdirSync(base).sort();
+  for (const v of old.slice(0, Math.max(0, old.length - 1))) rmSync(join(base, v), { recursive: true, force: true });
+  return { dir: join(base, n), rel: n };
+}
+
+export function planDraft(slug: string, dir: string, draft: any) {
+  try {
+    const video = applyDraft(dir, loadVideo(dir), draft);
+    const { dir: outDir, rel } = draftDir(slug);
+    /* the editor plays at 100%: the bed is made for the draft's cuts, not its speed */
+    const r = planSound(dir, video, { outDir, clock: finalClock(video, 1) });
+    const url = (file: string) =>
+      `/sound-draft/${encodeURIComponent(slug)}/${rel}/${encodeURIComponent(basename(file))}`;
+    const withUrl = ({ file, ...x }: any) => ({ ...x, url: url(file) });
+    return {
+      ok: true as const,
+      items: r.items.map(withUrl),
+      bed: r.bed ? withUrl(r.bed) : null,
+      warnings: r.warnings,
+      voice: r.voice,
+      ducking: r.ducking,
+    };
+  } catch (e: any) {
+    return { ok: false as const, error: e.message };
+  }
+}
+
+/* draft WAV: only inside .sound-draft/<slug>/ */
+export function draftFile(slug: string, rest: string): string | null {
+  const base = resolve(DRAFT_DIR, slug);
+  const abs = resolve(base, rest);
+  return abs.startsWith(base + sep) && abs.endsWith(".wav") && existsSync(abs) ? abs : null;
+}
+
+/* a file from the global kit, for the waveform */
+export function kitFile(name: string): string | null {
+  const abs = resolve(kitDir, name);
+  return abs.startsWith(resolve(kitDir) + sep) && abs.endsWith(".mp3") && existsSync(abs) ? abs : null;
+}
+
+/* writes the draft to scenes.json: the sound of each beat, each transition, the bed and the cuts */
+export function saveSound(dir: string, draft: any): Result {
+  const file = join(dir, "scenes.json");
+  const raw = readJson<any>(file);
+  if (!raw) return { ok: false, error: "scenes.json não existe" };
+  const video = loadVideo(dir);
+  const total = video.total_duration;
+  let changed = 0;
+  try {
+    for (const l of draft?.places ?? []) {
+      const i = raw.scenes.findIndex((c: any) => c.id === l.scene);
+      if (i < 0) throw new Error(`cena ${l.scene} não existe`);
+      const scene = raw.scenes[i];
+      const sounds = (l.sounds ?? []).map((s: any) => sanitizeSound(dir, s));
+      const sound = sounds.length === 0 ? null : sounds.length === 1 ? sounds[0] : sounds;
+      if (l.type === "transition") {
+        if (i === 0) throw new Error("a primeira cena não tem passagem");
+        const p = scene.transition && typeof scene.transition === "object" ? { ...scene.transition } : {};
+        if (sound) p.sound = sound;
+        else delete p.sound;
+        if (Object.keys(p).length) scene.transition = p;
+        else delete scene.transition;
+      } else {
+        const beat = (scene.beats ?? []).find((b: any) => b.element === l.element);
+        if (!beat) throw new Error(`${l.scene}: beat ${l.element} não existe`);
+        if (sound) beat.sound = sound;
+        else delete beat.sound;
+      }
+      changed++;
+    }
+    /* `bed` and `cuts` right before `scenes`, like the rest of the contract; empty is dropped */
+    let next = raw;
+    const beforeScenes = (field: string, value: any) => {
+      const r: any = {};
+      for (const [k, v] of Object.entries(next)) {
+        if (k === field) continue;
+        if (k === "scenes" && value) r[field] = value;
+        r[k] = v;
+      }
+      if (value && !(field in r)) r[field] = value;
+      next = r;
+    };
+    /* razor and drag clips (animation and voice), validated against the loaded durations; the default one is dropped */
+    const ref = structuredClone(video);
+    applyClips(ref, draft);
+    const match = (target: any, from: any) => {
+      delete target.video_em;
+      for (const k of ["clips", "video_offset"]) {
+        if (from && k in from) target[k] = from[k];
+        else delete target[k];
+      }
+    };
+    for (const c of raw.scenes) {
+      const rc = ref.scenes.find((x: any) => x.id === c.id);
+      if (draft?.scene_clips && c.id in draft.scene_clips) match(c, rc);
+      for (const l of c.lines ?? []) {
+        if (draft?.line_clips && l.id in draft.line_clips) {
+          const rl = rc?.lines?.find((x: any) => x.id === l.id);
+          if (rl && "clips" in rl) l.clips = rl.clips;
+          else delete l.clips;
+        }
+      }
+    }
+    if (draft && "bed" in draft) beforeScenes("bed", sanitizeBed(dir, draft.bed, total));
+    if (draft && "cuts" in draft) {
+      const c = normalizeCuts(draft.cuts, total, video.format.fps);
+      beforeScenes("cuts", c.length ? c : null);
+    }
+    if (draft && "speed" in draft) beforeScenes("speed", sanitizeSpeed(draft.speed));
+    const tmp = `${file}.${process.pid}.tmp`;
+    writeFileSync(tmp, JSON.stringify(next, null, 2) + "\n");
+    renameSync(tmp, file);
+  } catch (e: any) {
+    return { ok: false, error: e.message };
+  }
+  return {
+    ok: true,
+    output: `som salvo no scenes.json (${changed} lugar(es)${draft && "bed" in draft ? " e a cama" : ""}${draft?.cuts?.length ? `, ${draft.cuts.length} corte(s)` : ""}${draft && "speed" in draft ? `, velocidade ${Math.round(sanitizeSpeed(draft.speed) * 100)}%` : ""})`,
+  };
+}
+
+/* adds an Epidemic effect to the video's list: sound.mjs download itself (only the URL
+   captured in the player gets in), which writes the MP3 to sfx/ and the origin to sfx/sources.json */
+export async function downloadEffect(dir: string, body: any): Promise<Result> {
+  const url = String(body?.url ?? "").trim();
+  const name = String(body?.name ?? "").trim();
+  if (!url) return { ok: false, error: "cole a URL da Epidemic (audiocdn.epidemicsound.com/lqmp3/<id>.mp3)" };
+  const p = Bun.spawn([NODE, join(TOOLS_DIR, "sound.mjs"), "download", dir, url, ...(name ? [name] : [])], {
+    cwd: ROOT,
+    stdout: "pipe",
+    stderr: "pipe",
+    env: { ...process.env, OMNIVIDEO_ORIGIN: "studio" },
+  });
+  const [o, e, exit] = await Promise.all([new Response(p.stdout).text(), new Response(p.stderr).text(), p.exited]);
+  if (exit !== 0) return { ok: false, error: (e || o).trim().replace(/^erro:\s*/, "") || `sound.mjs saiu com ${exit}` };
+  return { ok: true, output: o.trim() };
+}
+
+/* adds a sound from an Epidemic page (playlist, theme, search): the editor's agent session opens it in
+   Chrome, plays the tracks, takes the lqmp3 URL from the player and runs sound.mjs download. The
+   timeline reloads when the agent stops. */
+export function captureFromPage(slug: string, body: any): ApiResult {
+  let page: URL;
+  try {
+    page = new URL(String(body?.url ?? "").trim());
+  } catch {
+    return { ok: false, error: "cole o link de uma página da Epidemic (https://www.epidemicsound.com/music/…)" };
+  }
+  if (page.protocol !== "https:" || !/^(www\.)?epidemicsound\.com$/.test(page.hostname))
+    return { ok: false, error: "o link precisa ser de epidemicsound.com" };
+  const name = String(body?.name ?? "").trim();
+  const search = page.pathname.split("/").filter(Boolean).pop() ?? "";
+  const message = [
+    `Adicione ao vídeo uma faixa desta página da Epidemic: ${page.href}`,
+    "Só isto: não mexa na timeline, no scenes.json nem na montagem, e não baixe de outra fonte.",
+    "1. Carregue as ferramentas do Claude in Chrome (ToolSearch) e abra a página numa aba nova; tire um screenshot, porque a lista só monta com a aba pintada.",
+    "2. Rode no javascript_tool o código de `node tools/sound.mjs capture 8`. Ele dá play nas faixas e devolve [{ title, duration, url }], com a URL https://audiocdn.epidemicsound.com/lqmp3/<id>.mp3 lida do `src` do player (a música usa a mesma URL dos efeitos; o blob: da página é outro recurso, ignore). Lista vazia: espere e tente de novo uma vez.",
+    `3. Escolha a primeira faixa cuja URL ainda não esteja em videos/${slug}/sfx/sources.json e baixe: \`node tools/sound.mjs download videos/${slug} <url> ${name || "<nome-curto-da-faixa>"} --search "${search}"\`. Música tem mais de 30 s; se a faixa for um efeito curto, diga isso.`,
+    "4. Feche a aba que você abriu e responda em uma linha: arquivo, título e duração.",
+    "Chrome fora do ar ou Epidemic sem responder: pare e diga o que abrir.",
+  ].join("\n");
+  return chatWith("edit", slug, message);
+}
+
+/* reassembles the export with the new sound: assemble.mjs waits in the queue and the stage follows it */
+export async function reassemble(dir: string): Promise<Result> {
+  const p = Bun.spawn([NODE, join(TOOLS_DIR, "assemble.mjs"), dir], {
+    cwd: ROOT,
+    stdout: "pipe",
+    stderr: "pipe",
+    env: { ...process.env, OMNIVIDEO_ORIGIN: "studio" },
+  });
+  const output = Promise.all([new Response(p.stdout).text(), new Response(p.stderr).text()]);
+  const early = await Promise.race([p.exited, Bun.sleep(2500).then(() => null)]);
+  if (early !== null && early !== 0) {
+    const [o, e] = await output;
+    return { ok: false, error: (e || o).trim() || `assemble.mjs saiu com ${early}` };
+  }
+  return { ok: true, output: early === 0 ? (await output)[0].trim() : "remontando (acompanhe na fila)" };
+}

package/studio/api/services/thumbnail.ts

@@ -0,0 +1,133 @@
+/* Thumbnail from the UI: the Publish stage asks the video's Claude (skill
+   av-thumbnail) for three random versions (v1–v3) or one with the user's
+   instruction (v4), and then only picks one. The two requests are separate: one
+   doesn't erase the other. A finished version can also be changed: Claude starts
+   from its HTML, keeps everything and changes only what was asked. Nothing is generated on its own: without the user's request, the
+   thumbnail/ dir doesn't even exist. tools/thumbnail.mjs, which the skill calls,
+   renders the PNGs and records thumbnail.json. */
+
+import { existsSync, mkdirSync, writeFileSync, renameSync } from "node:fs";
+import { join } from "node:path";
+import { NODE, TOOLS_DIR, run, readJson } from "./root";
+import { chatWith } from "./create";
+import { keepPrevious } from "../../../tools/history.mjs";
+
+type Result = { ok: true; output: string } | { ok: false; error: string };
+type ThumbnailRequests = {
+  random: { at: string } | null;
+  manual: { at: string; instruction: string } | null;
+  /* the change requested for each version (v1–v4); gone when the version is redone from scratch */
+  changes: Record<string, { at: string; instruction: string }>;
+};
+
+const VERSION = /^v[1-4]$/;
+
+function readRequests(file: string): ThumbnailRequests {
+  const p = readJson<any>(file);
+  /* old shape: a single request, the one for the three ({ at, request }; before the migration { em, pedido }) */
+  if (p && ("at" in p || "em" in p)) return { random: { at: p.at ?? p.em }, manual: null, changes: {} };
+  return { random: p?.random ?? null, manual: p?.manual ?? null, changes: p?.changes ?? {} };
+}
+
+function writeRequests(file: string, p: ThumbnailRequests) {
+  const tmp = `${file}.${process.pid}.tmp`;
+  writeFileSync(tmp, JSON.stringify(p, null, 2) + "\n");
+  renameSync(tmp, file);
+}
+
+export function requestThumbnail(
+  slug: string,
+  dir: string,
+  mode: unknown,
+  instruction: unknown,
+  version?: unknown,
+): Result {
+  const scenes = readJson<any>(join(dir, "scenes.json"));
+  if (!scenes?.format)
+    return { ok: false, error: "o vídeo ainda não tem scenes.json com formato: a thumbnail usa a proporção dele" };
+  const change = mode === "change";
+  const manual = mode === "manual";
+  const text = typeof instruction === "string" ? instruction.replace(/\s+/g, " ").trim().slice(0, 600) : "";
+  if (manual && !text) return { ok: false, error: "escreva a instrução da sua versão" };
+  const target = String(version ?? "");
+  if (change) {
+    if (!VERSION.test(target)) return { ok: false, error: `versão inválida: ${target || "(vazia)"}` };
+    if (!text) return { ok: false, error: "diga o que mudar nesta thumbnail" };
+    if (!existsSync(join(dir, "thumbnail", `${target}.html`)) || !existsSync(join(dir, "thumbnail", `${target}.png`)))
+      return { ok: false, error: `a versão ${target} ainda não foi criada` };
+  }
+
+  /* the request is recorded first: the UI shows "creating" right away and knows if
+     Claude stopped without delivering (request newer than the version) */
+  const thumbDir = join(dir, "thumbnail");
+  mkdirSync(thumbDir, { recursive: true });
+  const file = join(thumbDir, "request.json");
+  const before = readRequests(file);
+  const at = new Date().toISOString();
+  /* redoing from scratch drops the change recorded on the redone versions; a change only records that version's */
+  const withoutChange = (ids: string[]) =>
+    Object.fromEntries(Object.entries(before.changes).filter(([id]) => !ids.includes(id)));
+  writeRequests(
+    file,
+    change
+      ? { ...before, changes: { ...before.changes, [target]: { at, instruction: text } } }
+      : manual
+        ? { ...before, manual: { at, instruction: text }, changes: withoutChange(["v4"]) }
+        : { ...before, random: { at }, changes: withoutChange(["v1", "v2", "v3"]) },
+  );
+  /* the change's starting point (current HTML and PNG) goes to history/ before Claude touches it */
+  if (change)
+    keepPrevious(dir, "thumbnail", target, [`thumbnail/${target}.html`, `thumbnail/${target}.png`]).close({
+      keep: true,
+    });
+
+  const size = "`node tools/thumbnail.mjs videos/" + slug + " size`";
+  const message = (
+    change
+      ? [
+          `Pedido pela tela (etapa Publicar): ALTERE a thumbnail ${target} deste vídeo, que já existe, com a skill av-thumbnail, em videos/${slug}.`,
+          `Alteração pedida pelo usuário: ${text}`,
+          `Parta de thumbnail/${target}.html (a versão de agora já está em history/thumbnail/${target}/) e preserve LITERALMENTE tudo o que a alteração não cita: layout, textos, cores, fontes, tamanhos, posições, SVG, CSS. Use Edit com trocas pontuais; não reescreva o arquivo nem redesenhe do zero, e não "melhore" nada que não foi pedido. Mantenha o <title> e o <meta name="description">, e só mude a descrição se a alteração mudar o que a thumbnail mostra.`,
+          `Edite só thumbnail/${target}.html e renderize com \`node tools/thumbnail.mjs videos/${slug} render ${target}\`. Não mexa nas outras versões. Compare o PNG novo com o anterior (history/thumbnail/${target}/) e confirme que só mudou o pedido.`,
+        ]
+      : manual
+        ? [
+            `Pedido pela tela (etapa Publicar): gere a versão manual da thumbnail deste vídeo (v4) com a skill av-thumbnail, em videos/${slug}.`,
+            `Uma versão só, em HTML, SVG e CSS, no estilo do vídeo e na proporção dele (${size}), seguindo esta instrução do usuário: ${text}`,
+            "Escreva só thumbnail/v4.html e renderize com `node tools/thumbnail.mjs videos/" +
+              slug +
+              " render v4`. Não mexa em v1, v2 e v3.",
+          ]
+        : [
+            `Pedido pela tela (etapa Publicar): gere as três thumbnails aleatórias deste vídeo (v1, v2 e v3) com a skill av-thumbnail, em videos/${slug}.`,
+            `Três ideias diferentes, sorteadas com \`node tools/thumbnail.mjs videos/${slug} draw\`, em HTML, SVG e CSS, no estilo do vídeo e na proporção dele (${size}).`,
+            "Renderize com `node tools/thumbnail.mjs videos/" + slug + " render v1,v2,v3`. Não mexa na v4.",
+          ]
+  )
+    .concat("Leia os PNG e pare aí: a escolha é do usuário, na tela. Não publique nem refaça outra etapa.")
+    .join("\n");
+  const r = chatWith("video", slug, message);
+  if (!r.ok) {
+    writeRequests(file, before);
+    return { ok: false, error: r.error ?? "não deu para falar com o agente do vídeo" };
+  }
+  return {
+    ok: true,
+    output: change
+      ? `pedi a alteração da ${target} ao agente do vídeo: acompanhe na sessão acima`
+      : manual
+        ? "pedi a sua versão ao agente do vídeo: acompanhe na sessão acima"
+        : "pedi as três versões ao agente do vídeo: acompanhe na sessão acima",
+  };
+}
+
+export async function chooseThumbnail(dir: string, version: unknown): Promise<Result> {
+  const v = String(version ?? "");
+  if (v !== "none" && !VERSION.test(v)) return { ok: false, error: `versão inválida: ${v || "(vazia)"}` };
+  if (v !== "none" && !existsSync(join(dir, "thumbnail", `${v}.png`)))
+    return { ok: false, error: `a versão ${v} ainda não foi renderizada` };
+  const r = await run([NODE, join(TOOLS_DIR, "thumbnail.mjs"), dir, "choose", v]);
+  return r.code === 0
+    ? { ok: true, output: r.stdout.trim() }
+    : { ok: false, error: (r.stderr || r.stdout).trim() || `thumbnail.mjs saiu com ${r.code}` };
+}

package/studio/api/services/usage.ts

@@ -0,0 +1,27 @@
+/* Usage of the paid voices (Fish Audio and Cartesia). The accounting lives in tools/usage.py,
+   which the chat and the terminal also call; the studio only shows what it returns.
+   `refresh` asks the platforms now (and records the reading in .usage/). */
+
+import { join } from "node:path";
+import { PYTHON, TOOLS_DIR, run } from "./root";
+
+let cached: { at: number; data: unknown } | null = null;
+
+export async function getUsage(refresh = false): Promise<unknown> {
+  /* the UI reloads on every queue change; the local summary is cheap, but it doesn't need one Python per click */
+  if (!refresh && cached && Date.now() - cached.at < 3000) return cached.data;
+  const r = await run([PYTHON, join(TOOLS_DIR, "usage.py"), "summary", "--json", ...(refresh ? ["--live"] : [])]);
+  if (r.code !== 0) return { error: r.stderr.trim().split("\n").pop() || `usage.py saiu com código ${r.code}` };
+  try {
+    const data = JSON.parse(r.stdout);
+    cached = { at: Date.now(), data };
+    return data;
+  } catch {
+    return { error: "usage.py devolveu algo que não é JSON" };
+  }
+}
+
+/* the config or .env changed: the next summary asks usage.py again */
+export function forgetUsage() {
+  cached = null;
+}