overlay-factory-worker 0.1.0

package/scripts/report.ts

@@ -0,0 +1,127 @@
+/**
+ * How the What Prints episodes actually did, and what to change next.
+ *
+ *   npx tsx scripts/ig-sync.ts && npx tsx scripts/report.ts
+ *
+ * Ranks published episodes by comments per 1,000 reach against the account's
+ * own baseline. Likes are shown but not ranked on: reach varies by orders of
+ * magnitude and likes follow reach, so a like count says more about
+ * distribution than about whether the puzzle landed.
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+const ROOT = join(import.meta.dirname, "..");
+
+type Episode = {
+  card: string;
+  name: string;
+  difficulty?: string;
+  concept?: string;
+  format?: string;
+  caption: string | null;
+  permalink?: string;
+  postedAt?: string;
+  metrics?: Record<string, number>;
+};
+
+type Post = { insights?: Record<string, number>; comments: number };
+
+/** Comments per 1,000 accounts reached. */
+const rate = (comments: number, reach: number) =>
+  reach ? (comments / reach) * 1000 : 0;
+
+const median = (n: number[]) => {
+  if (!n.length) return 0;
+  const s = [...n].sort((a, b) => a - b);
+  const m = s.length >> 1;
+  return s.length % 2 ? s[m] : (s[m - 1] + s[m]) / 2;
+};
+
+const pad = (v: string | number, n: number) => String(v).padStart(n);
+
+const main = () => {
+  const index = JSON.parse(
+    readFileSync(join(ROOT, "episodes/index.json"), "utf8"),
+  ) as Episode[];
+  const posts = JSON.parse(
+    readFileSync(join(ROOT, "episodes/performance.json"), "utf8"),
+  ) as Post[];
+
+  // Baseline: every post we have reach for, series or not.
+  const withReach = posts.filter((p) => p.insights?.reach);
+  const baseline = median(
+    withReach.map((p) => rate(p.comments, p.insights!.reach)),
+  );
+
+  const quiz = index.filter((e) => e.format !== "debate");
+  const live = quiz
+    .filter((e) => e.metrics?.reach)
+    .map((e) => ({
+      ...e,
+      cpr: rate(e.metrics!.comments ?? 0, e.metrics!.reach),
+    }))
+    .sort((a, b) => b.cpr - a.cpr);
+
+  console.log(
+    `\nWHAT PRINTS — ${live.length} published of ${quiz.length} cards in the library`,
+  );
+  console.log(
+    `baseline: ${baseline.toFixed(2)} comments per 1k reach (median of ${withReach.length} posts)\n`,
+  );
+
+  if (!live.length) {
+    console.log("Nothing published yet with reach data — nothing to learn from.");
+    return;
+  }
+
+  console.log(
+    "  c/1k   vs base   reach   cmts  saves  diff    posted      card",
+  );
+  for (const e of live) {
+    const vs = baseline ? `${(e.cpr / baseline).toFixed(1)}x` : "-";
+    console.log(
+      `${pad(e.cpr.toFixed(1), 6)} ${pad(vs, 8)} ${pad(e.metrics!.reach, 7)} ` +
+        `${pad(e.metrics!.comments ?? 0, 6)} ${pad(e.metrics!.saved ?? 0, 6)}  ` +
+        `${pad(e.difficulty ?? "?", 6)} ${e.postedAt?.slice(0, 10)}  ${e.name}`,
+    );
+  }
+
+  // Grouped read-outs only once there's enough to be worth reading.
+  const MIN_PER_GROUP = 3;
+  const groups = (key: "difficulty" | "concept") => {
+    const m = new Map<string, number[]>();
+    for (const e of live) {
+      const k = e[key];
+      if (!k) continue;
+      m.set(k, [...(m.get(k) ?? []), e.cpr]);
+    }
+    const usable = [...m].filter(([, v]) => v.length >= MIN_PER_GROUP);
+    if (!usable.length) return;
+    console.log(`\nby ${key}:`);
+    for (const [k, v] of usable.sort(
+      (a, b) => median(b[1]) - median(a[1]),
+    ))
+      console.log(`  ${k.padEnd(10)} ${median(v).toFixed(1)} c/1k  (n=${v.length})`);
+  };
+
+  if (live.length >= 5) {
+    groups("difficulty");
+    groups("concept");
+  }
+
+  console.log("");
+  if (live.length < 5)
+    console.log(
+      `Only ${live.length} published — too few to tell a pattern from noise.\n` +
+        `Ship ~5 more before reading anything into the ranking. The library has\n` +
+        `${quiz.length - live.length} cards ready to go.`,
+    );
+  else
+    console.log(
+      "Feed the top performers' shared traits back into the rubric in the\n" +
+        "what-prints-card skill, and retire concepts that sit below baseline.",
+    );
+};
+
+main();

package/scripts/rerender-cards.ts

@@ -0,0 +1,116 @@
+/**
+ * Re-render the card library in the current design.
+ *
+ * The cards are baked PNGs, so a change to CodeCard.tsx only affects new ones —
+ * every puzzle already in the library keeps whatever it was rendered (or
+ * screenshotted) with. This regenerates them from the code stored in
+ * episodes/index.json, so one design change reaches everything.
+ *
+ *   npx tsx scripts/rerender-cards.ts --dry-run   # list what would change
+ *   npx tsx scripts/rerender-cards.ts             # do it
+ *
+ * The originals are moved to public/assets/cards-original/ rather than
+ * overwritten — they're the reference for what the design is imitating, and a
+ * few of them are screenshots that can't be reproduced at all.
+ *
+ * Verification and the quality gates are SKIPPED here on purpose: these
+ * snippets already passed them when they entered the library, and re-running
+ * every snippet through a real interpreter turns a re-skin into a long and
+ * flaky job. Use scripts/quality.ts to audit content.
+ */
+import { execFileSync } from "node:child_process";
+import {
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+} from "node:fs";
+import { join } from "node:path";
+
+const ROOT = join(__dirname, "..");
+const EPISODES = join(ROOT, "episodes");
+const CARDS = join(ROOT, "public/assets/cards");
+const ORIGINALS = join(ROOT, "public/assets/cards-original");
+
+type Entry = {
+  name?: string;
+  code?: string;
+  language?: string;
+  card?: string;
+  difficulty?: string;
+  retired?: string;
+};
+
+const asPng = (card: string) => card.replace(/\.(jpe?g|png)$/i, ".png");
+
+const main = () => {
+  const dryRun = process.argv.includes("--dry-run");
+  const index = JSON.parse(
+    readFileSync(join(EPISODES, "index.json"), "utf8"),
+  ) as Entry[];
+  const cards = JSON.parse(
+    readFileSync(join(EPISODES, "cards.json"), "utf8"),
+  ) as { card: string; language?: string }[];
+  const langOf = new Map(cards.map((c) => [c.card, c.language]));
+
+  const live = index.filter((e) => !e.retired && e.card);
+  const doable = live.filter((e) => e.code);
+  const stuck = live.filter((e) => !e.code);
+
+  console.log(
+    `${live.length} live cards · ${doable.length} re-renderable · ${stuck.length} without stored code`,
+  );
+  for (const e of stuck) {
+    console.log(`  ! ${e.name ?? e.card}: screenshot only, left as-is`);
+  }
+  if (dryRun) {
+    for (const e of doable) console.log(`  would re-render ${asPng(e.card!)}`);
+    return;
+  }
+
+  mkdirSync(ORIGINALS, { recursive: true });
+  let done = 0;
+
+  for (const e of doable) {
+    const png = asPng(e.card!);
+    const slug = png.replace(/\.png$/, "");
+    const src = join(CARDS, png);
+
+    // Keep the original once. A second run must not overwrite the archive with
+    // an already-re-rendered card.
+    const archived = join(ORIGINALS, png);
+    if (existsSync(src) && !existsSync(archived)) copyFileSync(src, archived);
+
+    const puzzle = {
+      slug,
+      name: e.name ?? slug,
+      language: e.language ?? langOf.get(e.card!) ?? "Python",
+      code: e.code,
+      difficulty: e.difficulty ?? "medium",
+    };
+    const tmp = join(ROOT, `.rerender-${slug}.json`);
+    writeFileSync(tmp, JSON.stringify(puzzle));
+    try {
+      execFileSync(
+        "npx",
+        ["tsx", "scripts/make-card.ts", tmp, "--no-verify", "--no-gates"],
+        { cwd: ROOT, stdio: ["ignore", "pipe", "pipe"], encoding: "utf8" },
+      );
+      done++;
+      console.log(`  ✓ ${png}`);
+    } catch (err) {
+      const e2 = err as { stdout?: string; stderr?: string };
+      const why = `${e2.stdout ?? ""}${e2.stderr ?? ""}`
+        .split("\n")
+        .find((l) => /Error/.test(l));
+      console.error(`  ✗ ${png}: ${why ?? "render failed"}`);
+    } finally {
+      execFileSync("rm", ["-f", tmp]);
+    }
+  }
+
+  console.log(`\n${done}/${doable.length} re-rendered. Originals: ${ORIGINALS}`);
+};
+
+main();