overlay-factory-worker 0.1.0

package/scripts/set-difficulty.ts

@@ -0,0 +1,62 @@
+/**
+ * Stamp a difficulty onto each episode in index.json.
+ *
+ * Ratings reflect how many people get the answer wrong, not how obscure the
+ * feature is: "easy" = most devs get it, "medium" = trips juniors, "hard" =
+ * trips seniors or has no single right answer.
+ *
+ * Edit the map and re-run to adjust; new-episode.ts reads these values.
+ */
+import { readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+const INDEX = join(import.meta.dirname, "../episodes/index.json");
+
+const DIFFICULTY: Record<string, "easy" | "medium" | "hard"> = {
+  "Donkey Kong Loop Chaos": "hard",
+  "Bowser's Type Trap": "easy",
+  "Mario's Inventory Bug": "medium",
+  "Toad's Lambda Factory": "hard",
+  "Luigi's Async Coin Collector": "medium",
+  "Boo's Equality Test": "medium",
+  "Mario's Copy Spell": "medium",
+  "Donkey Kong's Barrel Cleanup": "hard",
+  "Peach's Castle Registry": "easy",
+  "Star Power Scope": "medium",
+  "Warp Pipe Index": "easy",
+  "Koopa API Question": "medium",
+  "The Copy That Wasn't": "easy",
+  "The Thread Safety Debate": "hard",
+  "The Async Lie": "hard",
+  "Identity Crisis": "medium",
+  "The Sequel": "medium",
+  "The Finally Clause": "hard",
+  "The Floating Point War": "easy",
+  "Copy Machine": "medium",
+  "Equality vs Identity": "easy",
+  "The GIL Myth": "hard",
+  "NaN Logic": "medium",
+  "Async Doesn't Mean Async": "hard",
+  "The Timezone Trap": "hard",
+  "The API Retry Debate": "hard",
+  "The Survivor": "hard",
+};
+
+type Entry = { name: string; difficulty?: string };
+const index = JSON.parse(readFileSync(INDEX, "utf8")) as Entry[];
+
+let stamped = 0;
+const missing: string[] = [];
+for (const e of index) {
+  const d = DIFFICULTY[e.name];
+  if (d) {
+    e.difficulty = d;
+    stamped++;
+  } else {
+    missing.push(e.name);
+  }
+}
+
+writeFileSync(INDEX, JSON.stringify(index, null, 2) + "\n");
+console.log(`Stamped difficulty on ${stamped}/${index.length} episodes.`);
+if (missing.length) console.log(`  no rating for: ${missing.join(", ")}`);

package/scripts/state-dir.ts

@@ -0,0 +1,102 @@
+/**
+ * Where this machine's Overlay Factory state lives.
+ *
+ * In a git checkout — the way this repo has always run — state stays in the
+ * repo: episodes/, puzzles/, series/, public/assets/, public/fonts/custom/.
+ * All of those are already gitignored, because they were always per-machine.
+ *
+ * Installed from npm, the code lives under ~/.goosetools/overlay-app/
+ * node_modules/, which `update` deletes and reinstalls. Anything written there
+ * is lost on the next release — the learned looks, the puzzle library, the
+ * uploaded fonts, the record of which cards have been used. So state moves to
+ * ~/.goosetools/overlay/ and the package directory gets symlinks pointing at
+ * it.
+ *
+ * Symlinks rather than a path refactor on purpose: `staticFile("assets/...")`
+ * in the compositions, and every join(ROOT, ...) in these scripts, resolve to
+ * exactly what they always did. Remotion bundles from the package directory
+ * and sees a normal public/ folder. Nothing downstream needs to know which
+ * mode it's in.
+ */
+import {
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readdirSync,
+  realpathSync,
+  rmSync,
+  symlinkSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+const ROOT = join(__dirname, "..");
+
+/** A checkout has .git; an npm install doesn't (npm never packs it). */
+export const isCheckout = existsSync(join(ROOT, ".git"));
+
+export const STATE_ROOT = isCheckout
+  ? ROOT
+  : join(homedir(), ".goosetools", "overlay");
+
+/** [path inside the package, path inside the state dir] */
+const LINKS: [string, string][] = [
+  ["episodes", "episodes"],
+  ["puzzles", "puzzles"],
+  ["series", "series"],
+  [join("public", "assets"), "assets"],
+  [join("public", "fonts", "custom"), join("fonts", "custom")],
+];
+
+/**
+ * Point the package's writable directories at the state dir. Idempotent, and
+ * a no-op in a checkout. Safe to call on every worker start — which is what
+ * happens, because `update` replaces the package directory and takes the
+ * previous run's symlinks with it.
+ */
+export function ensureStateLinks(): void {
+  if (isCheckout) return;
+  for (const [rel, sub] of LINKS) {
+    const target = join(STATE_ROOT, sub);
+    const link = join(ROOT, rel);
+    mkdirSync(target, { recursive: true });
+    mkdirSync(dirname(link), { recursive: true });
+
+    if (existsSync(link) || isDanglingLink(link)) {
+      const stat = lstatSync(link);
+      if (stat.isSymbolicLink()) {
+        // Already ours? Leave it. Pointing somewhere else (an older layout)?
+        // Replace it — a stale link is how state silently splits in two.
+        if (safeRealpath(link) === target) continue;
+        rmSync(link);
+      } else if (readdirSync(link).length > 0) {
+        // A non-empty real directory shipped in the tarball. Linking over it
+        // would hide files the render needs, so leave it and say so once.
+        console.warn(
+          `[state] ${rel} is a real directory in the package — not linking it to ${target}.`,
+        );
+        continue;
+      } else {
+        rmSync(link, { recursive: true });
+      }
+    }
+    symlinkSync(target, link, "dir");
+  }
+}
+
+function isDanglingLink(p: string): boolean {
+  try {
+    lstatSync(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function safeRealpath(p: string): string | null {
+  try {
+    return realpathSync(p);
+  } catch {
+    return null;
+  }
+}

package/scripts/stock.ts

@@ -0,0 +1,254 @@
+/**
+ * Episode stock: the queue of things a series still has to say.
+ *
+ * A series defines two separate things, and conflating them is why only What
+ * Prints? could ever restock itself:
+ *
+ *   how it LOOKS     series.json "layers" + the HTML templates
+ *   what it SAYS     series.json "content" + episodes.json
+ *
+ * "content" is a brief — what one episode is, where to research it, what makes
+ * a bad one. episodes.json is the queue that brief produced. An overlay job
+ * with no inputs pops the next unused entry, exactly as What Prints? takes the
+ * next unused card from episodes/index.json.
+ *
+ * Restocking runs Claude on the user's own machine with WebSearch, the same
+ * arrangement the Brand Outreach worker already uses to research brands. The
+ * research is the point: a series like "Interviewer:" is only worth watching if
+ * the questions are ones people actually got asked, and that means going and
+ * finding them rather than inventing plausible-sounding ones.
+ */
+import { execFile } from "node:child_process";
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+} from "node:fs";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import type { SeriesField } from "./series";
+
+const execFileAsync = promisify(execFile);
+const ROOT = join(__dirname, "..");
+const SERIES_DIR = join(ROOT, "series");
+
+/** How a series sources what it says. Absent = the series can't restock. */
+export type ContentBrief = {
+  /** One sentence: what a single episode of this series IS. */
+  what: string;
+  /** Where to look, and what makes a good find. Drives the research pass. */
+  research?: string[];
+  /** Hard rules — what would make an episode wrong, not merely weak. */
+  rules?: string[];
+};
+
+export type Episode = {
+  /** Stable id, so "used" survives reordering and re-writes. */
+  id: string;
+  /** Field values, keyed by the series' own field keys. */
+  values: Record<string, string>;
+  /** Where this came from — a URL, a forum, or "written". Never invented. */
+  source?: string;
+  usedBy?: string;
+};
+
+type Store = { episodes: Episode[] };
+
+const storePath = (slug: string) => join(SERIES_DIR, slug, "episodes.json");
+
+const readStore = (slug: string): Store => {
+  const p = storePath(slug);
+  if (!existsSync(p)) return { episodes: [] };
+  try {
+    const parsed = JSON.parse(readFileSync(p, "utf8"));
+    return Array.isArray(parsed?.episodes) ? parsed : { episodes: [] };
+  } catch {
+    return { episodes: [] };
+  }
+};
+
+const writeStore = (slug: string, store: Store) => {
+  mkdirSync(join(SERIES_DIR, slug), { recursive: true });
+  writeFileSync(storePath(slug), JSON.stringify(store, null, 2) + "\n");
+};
+
+export const stockCount = (slug: string): number =>
+  readStore(slug).episodes.filter((e) => !e.usedBy).length;
+
+/** The next unused episode, or null when the series is dry. */
+export const nextEpisode = (slug: string): Episode | null =>
+  readStore(slug).episodes.find((e) => !e.usedBy) ?? null;
+
+export const markEpisodeUsed = (slug: string, id: string, label: string) => {
+  const store = readStore(slug);
+  const found = store.episodes.find((e) => e.id === id);
+  if (!found) return;
+  found.usedBy = label;
+  writeStore(slug, store);
+};
+
+/**
+ * Research and write new episodes for a series.
+ *
+ * Two things are enforced rather than trusted, because both are the difference
+ * between a series worth watching and one that quietly makes things up:
+ *
+ *  - every required field must be present, or the episode can't render
+ *  - anything the brief says is sourced must carry a real URL. A model asked
+ *    for "questions people were actually asked" will happily produce plausible
+ *    inventions; requiring the link is what makes the claim checkable.
+ */
+export const restock = async (opts: {
+  slug: string;
+  seriesName: string;
+  fields: SeriesField[];
+  content: ContentBrief;
+  count: number;
+}): Promise<Episode[]> => {
+  const existing = readStore(opts.slug).episodes;
+  const seen = existing.map((e) => Object.values(e.values).join(" · "));
+
+  const wantsSources = Boolean(opts.content.research?.length);
+
+  const prompt = `You are writing new episodes for a short-form video series.
+
+## The series
+${opts.seriesName}
+
+## What one episode is
+${opts.content.what}
+
+## The fields an episode must fill
+${opts.fields
+  .map(
+    (f) =>
+      `- "${f.key}" (${f.type}${f.required ? ", REQUIRED" : ""}): ${f.label}` +
+      (f.options ? ` — must be one of: ${f.options.join(", ")}` : "") +
+      (f.placeholder ? ` — e.g. "${f.placeholder}"` : ""),
+  )
+  .join("\n")}
+
+${
+  wantsSources
+    ? `## Research — do this before writing anything
+${opts.content.research!.map((r) => `- ${r}`).join("\n")}
+
+Use WebSearch and WebFetch. Every episode you return MUST carry a "source" URL
+you actually visited and that actually contains it. Do NOT invent a source, do
+NOT reuse a search-results page as a source, and do NOT attribute something to a
+company unless the page you found says so. If you can only find ${opts.count > 3 ? "a few" : "one or two"} real ones,
+return fewer episodes — a short honest list beats a padded invented one.`
+    : `## No research needed
+Write these from your own knowledge. Set "source" to "written".`
+}
+
+${
+  opts.content.rules?.length
+    ? `## Rules (breaking one makes the episode wrong, not just weak)
+${opts.content.rules.map((r) => `- ${r}`).join("\n")}`
+    : ""
+}
+
+${
+  seen.length
+    ? `## Already in the library — do NOT repeat these or near-duplicates
+${seen.slice(-40).map((s) => `- ${s}`).join("\n")}`
+    : ""
+}
+
+## Also remember
+This is burned onto a vertical video and read on a phone at arm's length.
+Keep every value short and punchy — a value that runs long gets shrunk to fit
+and stops being readable. No markdown, no quotes around the whole value.
+
+## Output — a JSON array and NOTHING else, no commentary, no code fence
+[
+  { "values": { ${opts.fields.map((f) => `"${f.key}": "..."`).join(", ")} }, "source": "https://…" }
+]
+
+Return at most ${opts.count}.`;
+
+  const { stdout } = await execFileAsync(
+    "claude",
+    [
+      "-p",
+      prompt,
+      "--output-format",
+      "text",
+      "--allowedTools",
+      wantsSources ? "WebSearch,WebFetch,Read" : "Read",
+    ],
+    { maxBuffer: 20 * 1024 * 1024, timeout: 20 * 60 * 1000 },
+  );
+
+  // Models like to wrap JSON in prose or a fence however firmly asked not to.
+  const text = stdout.trim();
+  const start = text.indexOf("[");
+  const end = text.lastIndexOf("]");
+  if (start === -1 || end === -1) {
+    throw new Error("No JSON array in the research output");
+  }
+
+  let raw: { values?: Record<string, string>; source?: string }[];
+  try {
+    raw = JSON.parse(text.slice(start, end + 1));
+  } catch (e) {
+    throw new Error(`Research output was not valid JSON: ${(e as Error).message}`);
+  }
+
+  const required = opts.fields.filter((f) => f.required).map((f) => f.key);
+  const seenSet = new Set(seen);
+  const accepted: Episode[] = [];
+
+  for (const [i, item] of raw.entries()) {
+    const values = item?.values;
+    if (!values || typeof values !== "object") continue;
+
+    const missing = required.filter((k) => !String(values[k] ?? "").trim());
+    if (missing.length) {
+      console.warn(`  ! episode ${i + 1} dropped: missing ${missing.join(", ")}`);
+      continue;
+    }
+
+    // A select field with an off-list value renders as nothing.
+    let badOption = false;
+    for (const f of opts.fields) {
+      if (f.options && values[f.key] && !f.options.includes(values[f.key])) {
+        console.warn(
+          `  ! episode ${i + 1} dropped: ${f.key}="${values[f.key]}" is not one of ${f.options.join(", ")}`,
+        );
+        badOption = true;
+      }
+    }
+    if (badOption) continue;
+
+    if (wantsSources && !/^https?:\/\//.test(item.source ?? "")) {
+      console.warn(`  ! episode ${i + 1} dropped: no real source URL`);
+      continue;
+    }
+
+    const key = Object.values(values).join(" · ");
+    if (seenSet.has(key)) {
+      console.warn(`  ! episode ${i + 1} dropped: duplicate`);
+      continue;
+    }
+    seenSet.add(key);
+
+    accepted.push({
+      // Deterministic id: no clock or randomness, and re-running can't collide.
+      id: `${opts.slug}-${existing.length + accepted.length + 1}`,
+      values: Object.fromEntries(
+        Object.entries(values).map(([k, v]) => [k, String(v).trim()]),
+      ),
+      source: item.source ?? "written",
+    });
+  }
+
+  if (accepted.length === 0) {
+    throw new Error("Nothing usable came back — every episode failed a check");
+  }
+
+  writeStore(opts.slug, { episodes: [...existing, ...accepted] });
+  return accepted;
+};

package/scripts/verify.ts

@@ -0,0 +1,149 @@
+/**
+ * Run a snippet for real and compare its output to the puzzle's stated answer.
+ *
+ * A "What Prints?" card whose answer is wrong is the worst thing this pipeline
+ * can ship — it's wrong in public, under a caption explaining why. So every card
+ * is executed before it renders, and a mismatch is a hard failure.
+ *
+ * Standalone audit of everything already in the library:
+ *   npx tsx scripts/verify.ts
+ */
+import { execFileSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+const ROOT = join(import.meta.dirname, "..");
+
+type Runner = { cmd: string; args: (code: string) => string[] };
+
+/** Languages we can actually execute. Anything else can't be auto-verified. */
+const RUNNERS: Record<string, Runner> = {
+  python: { cmd: "python3", args: (c) => ["-c", c] },
+  javascript: { cmd: "node", args: (c) => ["-e", c] },
+  node: { cmd: "node", args: (c) => ["-e", c] },
+};
+
+export type VerifyResult =
+  | { status: "ok"; output: string }
+  | { status: "loose"; output: string; expected: string }
+  | { status: "mismatch"; output: string; expected: string }
+  | { status: "error"; output: string }
+  | { status: "skipped"; reason: string };
+
+/** Trailing whitespace and blank lines shouldn't count as a difference. */
+const normalize = (s: string) =>
+  s
+    .replace(/\r\n/g, "\n")
+    .split("\n")
+    .map((l) => l.trimEnd())
+    .join("\n")
+    .trim();
+
+export const runSnippet = (code: string, lang: string) => {
+  const runner = RUNNERS[lang.toLowerCase()];
+  if (!runner) return null;
+  try {
+    const out = execFileSync(runner.cmd, runner.args(code), {
+      encoding: "utf8",
+      timeout: 10_000,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    return { output: out, threw: false };
+  } catch (e) {
+    const err = e as { stdout?: string; stderr?: string };
+    // A snippet whose answer IS the traceback still "prints" something.
+    return { output: (err.stdout ?? "") + (err.stderr ?? ""), threw: true };
+  }
+};
+
+/**
+ * The written answers use display conventions the interpreter doesn't: object
+ * ids are elided, long reprs get pretty-printed onto several lines, and a
+ * traceback is quoted as just its exception line under a "Raises:" label.
+ * Fold all of that away before deciding something is actually wrong.
+ */
+const loosen = (s: string) =>
+  s
+    .replace(/0x[0-9a-f]+/gi, "0x") // memory addresses vary per run
+    .replace(/<(\w+) object[^>]*>/g, "<$1 object>") // <coroutine object f at 0x..>
+    .replace(/^raises:?\s*/i, "")
+    .replace(/\s+/g, " ") // pretty-printing vs one line
+    .replace(/([[({])\s+|\s+([\])}])/g, "$1$2") // ...and its padding
+    .trim();
+
+export const verify = (
+  code: string,
+  lang: string,
+  answer: string | null | undefined,
+): VerifyResult => {
+  const run = runSnippet(code, lang);
+  if (!run) return { status: "skipped", reason: `no runner for ${lang}` };
+  if (!answer) return { status: "skipped", reason: "no answer stated" };
+
+  const actual = normalize(run.output);
+  const expected = normalize(answer);
+  if (actual === expected) return { status: "ok", output: actual };
+
+  const [a, e] = [loosen(actual), loosen(expected)];
+  // A thrown snippet passes if the stated exception line shows up in stderr.
+  if (a === e || (run.threw && e && a.includes(e)))
+    return { status: "loose", output: actual, expected };
+
+  if (run.threw && !expected) return { status: "error", output: actual };
+  return { status: "mismatch", output: actual, expected };
+};
+
+/** Audit mode: check every entry in episodes/index.json. */
+const main = () => {
+  const index = JSON.parse(
+    readFileSync(join(ROOT, "episodes/index.json"), "utf8"),
+  ) as {
+    card: string;
+    name: string;
+    code: string;
+    answer: string | null;
+    language?: string;
+    format?: string; // "debate" cards pose an opinion, not an output
+  }[];
+  const cards = JSON.parse(
+    readFileSync(join(ROOT, "episodes/cards.json"), "utf8"),
+  ) as { card: string; language: string }[];
+  const langOf = (card: string) =>
+    cards.find((c) => c.card === card)?.language ?? "python";
+
+  let ok = 0,
+    loose = 0,
+    bad = 0,
+    skipped = 0;
+  for (const e of index) {
+    if (e.format === "debate") {
+      skipped++;
+      console.log(`SKIP  ${e.name} — debate card, no printed output`);
+      continue;
+    }
+    const r = verify(e.code, langOf(e.card), e.answer);
+    if (r.status === "ok") {
+      ok++;
+      continue;
+    }
+    if (r.status === "loose") {
+      loose++;
+      console.log(`~ok   ${e.name} — matches after normalizing formatting`);
+      continue;
+    }
+    if (r.status === "skipped") {
+      skipped++;
+      console.log(`SKIP  ${e.name} — ${r.reason}`);
+      continue;
+    }
+    bad++;
+    console.log(`\nBAD   ${e.name}  (${e.card})`);
+    console.log(`  stated: ${JSON.stringify(e.answer)}`);
+    console.log(`  actual: ${JSON.stringify(r.output)}`);
+  }
+  console.log(
+    `\n${ok} exact, ${loose} match after normalizing, ${bad} wrong, ${skipped} skipped`,
+  );
+};
+
+if (process.argv[1]?.endsWith("verify.ts")) main();