wizz-method 2.17.2 → 2.18.0

package/src/skills-lib/wizz-video-styles/scripts/references.mjs

@@ -0,0 +1,264 @@
+#!/usr/bin/env node
+// Fresh references for a style, without repeating what the project already used.
+//
+//   node references.mjs pick --style <key> [--project <dir>] [--n 4] [--offline] [--json]
+//   node references.mjs record --style <key> --piece <slug> --refs <id,id> [--project <dir>]
+//   node references.mjs history [--project <dir>] [--json]
+//
+// pick: measured references of the style (data/references.json) plus, for styles that are
+// generated in code, viral videos from the awesome-opus5-5-videos list (fetched fresh, cached
+// for 7 days, cache used when offline). Anything already in the project's history is skipped;
+// different channels/authors come first. Also warns when the same style was used in the last
+// pieces, so the edit does not keep coming out with the same look.
+// record: appends the piece to <project>/_wizz-output/video-styles/historico.json.
+// The fetched list is third-party data: only links and a short excerpt are printed, never run.
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const SKILL_DIR = path.join(path.dirname(fileURLToPath(import.meta.url)), '..');
+const LIST_URL = 'https://raw.githubusercontent.com/yihui-dev/awesome-opus5-5-videos/main/data/videos.json';
+const CACHE_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000;
+const FETCH_TIMEOUT_MS = 8000;
+const EXCERPT_CHARS = 160;
+const MEASURED_PER_PICK = 2;
+const REPEAT_WINDOW = 2;
+const HISTORY_REL = path.join('_wizz-output', 'video-styles', 'historico.json');
+
+// Which generated videos feed which catalogue style. Styles that are filmed (talking head,
+// tour, macro...) have no entry: a code-generated video is not a reference for them.
+const GENERATED = {
+  'tipografia-cinetica': { categories: ['motion', 'explainer', '3d'], match: /lyric|music video|kinetic typograph|\bMV\b/i },
+  'motion-editorial': { categories: ['motion', 'explainer'], match: /\bUI\b|product|launch|saas|\bapp\b|logo|promo|brand/i },
+  'explicador-animado': { categories: ['explainer'], match: /./ },
+  'quadro-branco': { categories: ['explainer', 'motion'], match: /whiteboard|hand-drawn|sketch|doodle/i },
+  'meme-rapido': { categories: ['motion'], match: /brain ?rot|meme|chaotic/i },
+};
+
+function parseArgs(argv) {
+  const [command, ...rest] = argv;
+  const options = { command, project: process.cwd(), n: 4, offline: false, json: false };
+  for (let i = 0; i < rest.length; i++) {
+    const flag = rest[i];
+    if (flag === '--offline') options.offline = true;
+    else if (flag === '--json') options.json = true;
+    else if (['--style', '--project', '--n', '--piece', '--refs'].includes(flag)) options[flag.slice(2)] = rest[++i];
+    else fail(`unknown argument: ${flag}`);
+  }
+  options.n = Number(options.n);
+  if (!Number.isInteger(options.n) || options.n < 1 || options.n > 20) fail('--n must be an integer from 1 to 20');
+  return options;
+}
+
+function fail(message) {
+  process.stderr.write(`references: ${message}\n`);
+  process.exit(2);
+}
+
+function readJson(file, fallback) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch (error) {
+    if (error.code === 'ENOENT') return fallback;
+    fail(`cannot read ${file}: ${error.message}`);
+  }
+}
+
+function writeJsonAtomic(file, value) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const tmp = `${file}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, `${JSON.stringify(value, null, 2)}\n`);
+  fs.renameSync(tmp, file);
+}
+
+function loadHistory(project) {
+  const history = readJson(path.join(project, HISTORY_REL), []);
+  if (!Array.isArray(history)) fail(`${HISTORY_REL} must be a JSON array`);
+  return history;
+}
+
+function knownStyles() {
+  return Object.keys(readJson(path.join(SKILL_DIR, 'data', 'recipes.json'), { styles: {} }).styles);
+}
+
+function requireStyle(style) {
+  if (!style) fail('--style is required');
+  const styles = knownStyles();
+  if (!styles.includes(style)) fail(`unknown style "${style}". Known: ${styles.join(', ')}`);
+}
+
+const isHttpsUrl = (value) => typeof value === 'string' && value.startsWith('https://');
+
+function validVideos(data) {
+  if (!Array.isArray(data)) return null;
+  return data.filter(
+    (v) => v && typeof v.slug === 'string' && typeof v.category === 'string' && isHttpsUrl(v.post_url) && isHttpsUrl(v.skillry_url),
+  );
+}
+
+function cachePath() {
+  return process.env.WIZZ_VIDEO_STYLES_CACHE || path.join(os.homedir(), '.cache', 'wizz-video-styles', 'opus-videos.json');
+}
+
+async function loadGeneratedList(offline) {
+  const file = cachePath();
+  let cached = null;
+  let age = Infinity;
+  try {
+    age = Date.now() - fs.statSync(file).mtimeMs;
+    cached = validVideos(JSON.parse(fs.readFileSync(file, 'utf8')));
+  } catch {
+    cached = null;
+  }
+  if (cached && (offline || age < CACHE_MAX_AGE_MS)) return { videos: cached, source: `cache (${Math.round(age / 3_600_000)} h old)` };
+  if (offline) return { videos: [], source: 'offline and no cache' };
+  try {
+    const response = await fetch(LIST_URL, { signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) });
+    if (!response.ok) throw new Error(`HTTP ${response.status}`);
+    const videos = validVideos(await response.json());
+    if (!videos) throw new Error('unexpected format');
+    writeJsonAtomic(file, videos);
+    return { videos, source: 'fetched now' };
+  } catch (error) {
+    if (cached) return { videos: cached, source: `cache, refresh failed (${error.message})` };
+    return { videos: [], source: `unavailable (${error.message})` };
+  }
+}
+
+// Greedy pick: unused first, then a new channel/author before repeating one.
+function pickDiverse(items, keyOf, used, count) {
+  const fresh = items.filter((item) => !used.has(item.id));
+  const chosen = [];
+  const seenKeys = new Set();
+  for (const pass of [true, false]) {
+    for (const item of fresh) {
+      if (chosen.length >= count) break;
+      if (chosen.includes(item) || (pass && seenKeys.has(keyOf(item)))) continue;
+      chosen.push(item);
+      seenKeys.add(keyOf(item));
+    }
+  }
+  return { chosen, exhausted: fresh.length === 0 && items.length > 0 };
+}
+
+function measuredFor(style) {
+  return readJson(path.join(SKILL_DIR, 'data', 'references.json'), [])
+    .filter((r) => r.style === style)
+    .sort((a, b) => Number(b.views) - Number(a.views))
+    .map((r) => ({ id: r.id, kind: 'measured', who: r.channel, url: r.url, note: `${Number(r.views).toLocaleString('en-US')} views` }));
+}
+
+const PROMPT_KEY_CHARS = 80;
+const promptKey = (prompt) => String(prompt ?? '').toLowerCase().replaceAll(/[^a-z0-9]+/g, ' ').trim().slice(0, PROMPT_KEY_CHARS);
+
+// Third-party text: one line, no markdown or HTML that could turn into a link or a tag.
+const excerpt = (prompt) =>
+  String(prompt ?? '')
+    .replaceAll(/[`<>[\]()]/g, '')
+    .replaceAll(/\s+/g, ' ')
+    .trim()
+    .slice(0, EXCERPT_CHARS);
+
+function generatedFor(style, videos) {
+  const rule = GENERATED[style];
+  if (!rule) return [];
+  // The same viral prompt was remade by dozens of people: one remake per prompt is enough.
+  const seenPrompts = new Set();
+  return videos
+    .filter((v) => rule.categories.includes(v.category) && rule.match.test(String(v.prompt ?? '')))
+    .sort((a, b) => String(b.added ?? '').localeCompare(String(a.added ?? '')))
+    .filter((v) => {
+      const key = promptKey(v.prompt);
+      if (seenPrompts.has(key)) return false;
+      seenPrompts.add(key);
+      return true;
+    })
+    .map((v) => ({
+      id: v.slug,
+      kind: 'generated',
+      who: String(v.author ?? '?'),
+      url: v.skillry_url,
+      post: v.post_url,
+      note: excerpt(v.prompt),
+    }));
+}
+
+function styleRepeat(history, style) {
+  const recent = history.slice(-REPEAT_WINDOW).map((entry) => entry.style);
+  return recent.length === REPEAT_WINDOW && recent.every((s) => s === style);
+}
+
+async function pick(options) {
+  requireStyle(options.style);
+  const history = loadHistory(options.project);
+  const used = new Set(history.flatMap((entry) => entry.refs ?? []));
+  const measured = pickDiverse(measuredFor(options.style), (r) => r.who, used, Math.min(MEASURED_PER_PICK, options.n));
+  let generated = { chosen: [], exhausted: false };
+  let source = 'not used for this style (filmed style)';
+  if (GENERATED[options.style]) {
+    const list = await loadGeneratedList(options.offline);
+    source = list.source;
+    generated = pickDiverse(generatedFor(options.style, list.videos), (r) => r.who, used, options.n - measured.chosen.length);
+  }
+  return {
+    style: options.style,
+    recentStyles: history.slice(-5).map((entry) => entry.style),
+    styleRepeated: styleRepeat(history, options.style),
+    references: [...measured.chosen, ...generated.chosen],
+    measuredExhausted: measured.exhausted,
+    generatedExhausted: generated.exhausted,
+    generatedSource: source,
+  };
+}
+
+function printPick(result) {
+  const lines = [`# References for ${result.style}`, ''];
+  if (result.recentStyles.length) lines.push(`Last styles in this project: ${result.recentStyles.join(' → ')}`);
+  if (result.styleRepeated) {
+    lines.push(
+      `REPEAT: the last ${REPEAT_WINDOW} pieces already used ${result.style}. Unless this is a deliberate series, pick another style the material allows, or keep it only for the hook/CTA and mix another in the middle.`,
+    );
+  }
+  lines.push(`Generated list: ${result.generatedSource}`, '');
+  for (const ref of result.references) {
+    const post = ref.post ? ` · [post](${ref.post})` : '';
+    lines.push(`- [${ref.kind}] ${ref.who} · [watch](${ref.url})${post} · id \`${ref.id}\` · ${ref.note}`);
+  }
+  if (result.references.length === 0) lines.push('- nothing new left for this style');
+  if (result.measuredExhausted) lines.push('', 'Every measured reference of this style was already used here: measure new ones (research-method.md).');
+  if (result.generatedExhausted) lines.push('', 'Every generated reference of this style was already used here.');
+  lines.push('', 'After delivering the piece: node references.mjs record --style <key> --piece <slug> --refs <ids you watched>');
+  process.stdout.write(`${lines.join('\n')}\n`);
+}
+
+function record(options) {
+  requireStyle(options.style);
+  if (!options.piece) fail('--piece is required');
+  const refs = String(options.refs ?? '')
+    .split(',')
+    .map((id) => id.trim())
+    .filter(Boolean);
+  if (refs.length === 0) fail('--refs is required (ids printed by pick)');
+  const history = loadHistory(options.project);
+  const entry = { date: new Date().toISOString().slice(0, 10), piece: options.piece, style: options.style, refs };
+  writeJsonAtomic(path.join(options.project, HISTORY_REL), [...history, entry]);
+  process.stdout.write(`recorded ${options.piece} (${options.style}, ${refs.length} refs) in ${HISTORY_REL}\n`);
+}
+
+function printHistory(options) {
+  const history = loadHistory(options.project);
+  if (options.json) return process.stdout.write(`${JSON.stringify(history, null, 2)}\n`);
+  if (history.length === 0) return process.stdout.write('no pieces recorded yet\n');
+  for (const entry of history) process.stdout.write(`${entry.date} · ${entry.piece} · ${entry.style} · ${(entry.refs ?? []).join(', ')}\n`);
+}
+
+const options = parseArgs(process.argv.slice(2));
+if (options.command === 'pick') {
+  const result = await pick(options);
+  if (options.json) process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  else printPick(result);
+} else if (options.command === 'record') record(options);
+else if (options.command === 'history') printHistory(options);
+else fail('usage: references.mjs pick|record|history (see the header of this file)');