goosetools-worker 0.1.2 → 0.2.2

package/worker/service.js

@@ -0,0 +1,395 @@
+// Background-service install/uninstall for the Goose Tools worker.
+// `install` makes the worker persistent: token saved to ~/.goosetools/env,
+// a stable copy of this package installed under ~/.goosetools/app, and a
+// login service registered (launchd LaunchAgent on macOS, a logon Scheduled
+// Task on Windows) so the worker runs whenever the computer is on — no
+// terminal window needed.
+//
+// `update` re-runs that install against the newest code, reusing the saved
+// token; `status` reports what's actually running, for debugging.
+
+import { execSync } from "node:child_process";
+import {
+  chmodSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { FFMPEG_INSTALL_CMD } from "../src/video.js";
+
+export const GOOSE_DIR = join(homedir(), ".goosetools");
+const ENV_FILE = join(GOOSE_DIR, "env");
+const APP_PREFIX = join(GOOSE_DIR, "app");
+const INSTALLED_CLI = join(APP_PREFIX, "node_modules", "goosetools-worker", "worker", "cli.js");
+
+const MAC_LABEL = "com.goosetools.worker";
+const MAC_PLIST = join(homedir(), "Library", "LaunchAgents", `${MAC_LABEL}.plist`);
+const WIN_TASK = "GooseTools Worker";
+const WIN_VBS = join(GOOSE_DIR, "run-worker.vbs");
+
+function sh(cmd, opts = {}) {
+  return execSync(cmd, { stdio: ["ignore", "pipe", "pipe"], ...opts })
+    .toString()
+    .trim();
+}
+
+function quietSh(cmd) {
+  try {
+    sh(cmd);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// Sync probe — the CLI's install/status paths are synchronous, and this is
+// only ever two cheap `-version` calls.
+function hasFfmpeg() {
+  return quietSh("ffmpeg -version") && quietSh("ffprobe -version");
+}
+
+function npmGlobalBin() {
+  try {
+    const prefix = sh("npm prefix -g", { shell: true });
+    return process.platform === "win32" ? prefix : join(prefix, "bin");
+  } catch {
+    return "";
+  }
+}
+
+function servicePath() {
+  // Everything the daemon needs to find: node itself, the npm-global bin
+  // (where `claude` lives), plus the usual suspects.
+  const parts = [
+    dirname(process.execPath),
+    npmGlobalBin(),
+    ...(process.platform === "win32"
+      ? [process.env.PATH ?? ""]
+      : [
+          "/opt/homebrew/bin",
+          "/usr/local/bin",
+          `${process.env.HOME ?? ""}/.local/bin`,
+          "/usr/bin",
+          "/bin",
+          "/usr/sbin",
+          "/sbin",
+        ]),
+  ].filter(Boolean);
+  return [...new Set(parts)].join(process.platform === "win32" ? ";" : ":");
+}
+
+function writeEnvFile({ url, token }) {
+  mkdirSync(GOOSE_DIR, { recursive: true });
+  writeFileSync(ENV_FILE, `GOOSETOOLS_URL=${url}\nWORKER_TOKEN=${token}\n`);
+  chmodSync(ENV_FILE, 0o600);
+}
+
+function installStableCopy(root) {
+  console.log("Setting up the background copy (this can take a minute)…");
+  mkdirSync(APP_PREFIX, { recursive: true });
+  // From a git checkout (development), install the checkout itself;
+  // normal npx users get the published package.
+  const source = existsSync(join(root, ".git")) ? `"${root}"` : "goosetools-worker@latest";
+  execSync(`npm install --no-fund --no-audit --loglevel=error --prefix "${APP_PREFIX}" ${source}`, {
+    stdio: ["ignore", "inherit", "inherit"],
+    shell: true,
+  });
+  if (!existsSync(INSTALLED_CLI)) {
+    throw new Error("background copy did not install where expected");
+  }
+}
+
+// ── macOS (launchd) ──────────────────────────────────────────────────────────
+
+function macPlist() {
+  const esc = (s) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>${MAC_LABEL}</string>
+    <key>ProgramArguments</key>
+    <array>
+        <string>${esc(process.execPath)}</string>
+        <string>${esc(INSTALLED_CLI)}</string>
+        <string>run</string>
+    </array>
+    <key>RunAtLoad</key>
+    <true/>
+    <key>KeepAlive</key>
+    <true/>
+    <key>ThrottleInterval</key>
+    <integer>30</integer>
+    <key>StandardOutPath</key>
+    <string>${esc(join(GOOSE_DIR, "worker.log"))}</string>
+    <key>StandardErrorPath</key>
+    <string>${esc(join(GOOSE_DIR, "worker.err.log"))}</string>
+    <key>EnvironmentVariables</key>
+    <dict>
+        <key>PATH</key>
+        <string>${esc(servicePath())}</string>
+    </dict>
+</dict>
+</plist>
+`;
+}
+
+function macInstall() {
+  mkdirSync(dirname(MAC_PLIST), { recursive: true });
+  writeFileSync(MAC_PLIST, macPlist());
+  const uid = process.getuid();
+  // Re-registering: tear down any previous copy first, then bootstrap.
+  quietSh(`launchctl bootout gui/${uid}/${MAC_LABEL}`);
+  if (!quietSh(`launchctl bootstrap gui/${uid} "${MAC_PLIST}"`)) {
+    // Older macOS fallback.
+    quietSh(`launchctl unload "${MAC_PLIST}"`);
+    execSync(`launchctl load -w "${MAC_PLIST}"`, { stdio: "ignore" });
+  }
+}
+
+function macUninstall() {
+  quietSh(`launchctl bootout gui/${process.getuid()}/${MAC_LABEL}`);
+  quietSh(`launchctl unload "${MAC_PLIST}"`);
+  rmSync(MAC_PLIST, { force: true });
+}
+
+// ── Windows (Scheduled Task at logon, hidden window) ─────────────────────────
+
+function winInstall() {
+  // wscript launches the worker with no console window.
+  const vbs = `CreateObject("WScript.Shell").Run """${process.execPath}"" ""${INSTALLED_CLI}"" run", 0, False\r\n`;
+  writeFileSync(WIN_VBS, vbs);
+  quietSh(`schtasks /End /TN "${WIN_TASK}"`);
+  quietSh(`schtasks /Delete /F /TN "${WIN_TASK}"`);
+  execSync(`schtasks /Create /F /SC ONLOGON /TN "${WIN_TASK}" /TR "wscript.exe \\"${WIN_VBS}\\""`, {
+    stdio: "ignore",
+    shell: true,
+  });
+  execSync(`schtasks /Run /TN "${WIN_TASK}"`, { stdio: "ignore", shell: true });
+}
+
+function winUninstall() {
+  quietSh(`schtasks /End /TN "${WIN_TASK}"`);
+  quietSh(`schtasks /Delete /F /TN "${WIN_TASK}"`);
+  rmSync(WIN_VBS, { force: true });
+}
+
+// ── Public commands ──────────────────────────────────────────────────────────
+
+export function install({ url, token, root }) {
+  if (!token) {
+    console.error("Missing worker token. Run: goosetools-worker install --url " + url + " --token gt_…");
+    process.exit(1);
+  }
+  writeEnvFile({ url, token });
+  installStableCopy(root);
+  if (process.platform === "darwin") macInstall();
+  else if (process.platform === "win32") winInstall();
+  else {
+    console.error(
+      "Automatic background setup isn't available on this OS yet.\n" +
+        "Run the worker directly instead:  goosetools-worker run",
+    );
+    process.exit(1);
+  }
+  console.log(
+    "\n✓ All set! Your computer now connects to Goose Tools by itself —\n" +
+      "  in the background, whenever it's on, even after a restart.\n" +
+      "  You can close this window.\n\n" +
+      `  Logs:      ${join(GOOSE_DIR, "worker.log")}\n` +
+      "  Turn off:  npx --yes goosetools-worker uninstall\n",
+  );
+  // Optional, and only worth a mention once the required setup has succeeded:
+  // photo carousels are already fully working at this point.
+  if (!hasFfmpeg()) {
+    console.log(
+      "  Optional — want video slides?\n" +
+        "  Carousels made from photos work right now. To also put video clips\n" +
+        "  in a carousel, install ffmpeg (one time, a couple of minutes):\n\n" +
+        `      ${FFMPEG_INSTALL_CMD}\n`,
+    );
+  }
+}
+
+// Removes THIS worker, not the whole ~/.goosetools directory. It used to take
+// the directory, which was harmless while everything in there was either this
+// worker's or re-derivable from the server — and stopped being harmless when
+// the Overlay Factory started keeping its puzzle library, learned looks and
+// used-card record in ~/.goosetools/overlay. Nothing else has a copy of those,
+// and `npx goosetools uninstall` runs this. The shared token file stays: the
+// other workers are still using it.
+export function uninstall() {
+  if (process.platform === "darwin") macUninstall();
+  else if (process.platform === "win32") winUninstall();
+  rmSync(APP_PREFIX, { recursive: true, force: true });
+  rmSync(join(GOOSE_DIR, "worker.log"), { force: true });
+  rmSync(join(GOOSE_DIR, "worker.err.log"), { force: true });
+  console.log("✓ Carousel worker removed. This computer no longer makes carousels.");
+}
+
+// ── update ───────────────────────────────────────────────────────────────────
+// The daemon runs the COPY under ~/.goosetools/app, not wherever you ran this
+// from — so new code only reaches it by reinstalling that copy. Re-registering
+// the service also restarts it, which is what actually loads the new code
+// (Node reads every module once, at startup).
+export function update({ root }) {
+  const saved = readEnvFile();
+  if (!saved.WORKER_TOKEN) {
+    console.error(
+      "No saved worker token — this computer hasn't been connected yet.\n" +
+        "Get a token at https://goosetools.com/dashboard/carousel and run:\n" +
+        "  npx --yes goosetools-worker@latest install --token gt_…",
+    );
+    process.exit(1);
+  }
+  const before = installedVersion();
+  installStableCopy(root);
+  if (process.platform === "darwin") macInstall();
+  else if (process.platform === "win32") winInstall();
+  else {
+    console.error("Automatic background setup isn't available on this OS yet.");
+    process.exit(1);
+  }
+  const after = installedVersion();
+  console.log(
+    after && before && after !== before
+      ? `\n✓ Updated ${before} → ${after} and restarted. Nothing else to do.\n`
+      : `\n✓ Worker reinstalled (version ${after ?? "unknown"}) and restarted.\n`,
+  );
+}
+
+// ── status ───────────────────────────────────────────────────────────────────
+function readEnvFile() {
+  if (!existsSync(ENV_FILE)) return {};
+  return Object.fromEntries(
+    readFileSync(ENV_FILE, "utf8")
+      .split("\n")
+      .filter((l) => l.includes("=") && !l.trim().startsWith("#"))
+      .map((l) => [l.slice(0, l.indexOf("=")).trim(), l.slice(l.indexOf("=") + 1).trim()]),
+  );
+}
+
+function installedVersion() {
+  try {
+    const pkg = join(APP_PREFIX, "node_modules", "goosetools-worker", "package.json");
+    return JSON.parse(readFileSync(pkg, "utf8")).version ?? null;
+  } catch {
+    return null;
+  }
+}
+
+function latestVersion() {
+  try {
+    return sh("npm view goosetools-worker version", { shell: true, timeout: 15000 });
+  } catch {
+    return null; // offline, or npm unreachable — not an error worth failing on
+  }
+}
+
+// -1 / 0 / 1, comparing x.y.z numerically. Anything unparseable sorts equal so
+// an odd version string never nags the user to "update" in a loop.
+function compareVersions(a, b) {
+  const parts = (v) => String(v).split(".").map((n) => Number.parseInt(n, 10) || 0);
+  const [pa, pb] = [parts(a), parts(b)];
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    if ((pa[i] ?? 0) !== (pb[i] ?? 0)) return (pa[i] ?? 0) < (pb[i] ?? 0) ? -1 : 1;
+  }
+  return 0;
+}
+
+// launchctl prints "<pid>\t<last exit>\t<label>"; a "-" pid means registered
+// but not currently running.
+function servicePid() {
+  try {
+    if (process.platform === "darwin") {
+      const line = sh(`launchctl list | grep ${MAC_LABEL}`, { shell: true });
+      const pid = line.split(/\s+/)[0];
+      return pid === "-" ? null : pid;
+    }
+    const out = sh(`schtasks /Query /TN "${WIN_TASK}" /FO LIST`, { shell: true });
+    return /Running/i.test(out) ? "running" : null;
+  } catch {
+    return null;
+  }
+}
+
+function tail(file, n) {
+  try {
+    return readFileSync(file, "utf8").trimEnd().split("\n").slice(-n).join("\n");
+  } catch {
+    return "";
+  }
+}
+
+// How long ago a log was last written. Without this, days-old errors read as
+// a live outage — the single most misleading thing in a log tail.
+function lastWritten(file) {
+  try {
+    const ms = Date.now() - statSync(file).mtimeMs;
+    const mins = Math.round(ms / 60000);
+    if (mins < 1) return "just now";
+    if (mins < 60) return `${mins} min ago`;
+    const hours = Math.round(mins / 60);
+    if (hours < 24) return `${hours} hr ago`;
+    return `${Math.round(hours / 24)} days ago`;
+  } catch {
+    return "unknown";
+  }
+}
+
+export function status() {
+  const ok = (b) => (b ? "✓" : "✗");
+  const env = readEnvFile();
+  const installed = installedVersion();
+  const latest = latestVersion();
+  const pid = servicePid();
+  const url = env.GOOSETOOLS_URL ?? "https://goosetools.com";
+
+  console.log("\nGoose Tools worker — status\n");
+  console.log(`  ${ok(installed)} Installed        ${installed ?? "not installed"}`);
+  // Ahead of npm means a local dev install — say so rather than telling the
+  // user to "update" to something older than what they're running.
+  const cmp = installed && latest ? compareVersions(installed, latest) : 0;
+  const stale = cmp < 0;
+  if (latest) {
+    const note = stale ? "  ← update available" : cmp > 0 ? "  (you're ahead — local dev build)" : "";
+    console.log(`  ${ok(!stale)} Latest on npm    ${latest}${note}`);
+  } else {
+    console.log("  · Latest on npm    couldn't check (offline?)");
+  }
+  console.log(`  ${ok(pid)} Running          ${pid ? `yes (pid ${pid})` : "no"}`);
+  console.log(`  ${ok(env.WORKER_TOKEN)} Token saved      ${env.WORKER_TOKEN ? "yes" : "no — run install --token gt_…"}`);
+  // Not an "✗": a worker without ffmpeg is healthy, it just can't do video.
+  console.log(
+    `  ${hasFfmpeg() ? "✓" : "·"} Video slides     ${
+      hasFfmpeg() ? "yes (ffmpeg found)" : `photos only — for video: ${FFMPEG_INSTALL_CMD}`
+    }`,
+  );
+  console.log(`  · Server           ${url}`);
+  console.log(`  · Logs             ${join(GOOSE_DIR, "worker.log")}`);
+
+  const errFile = join(GOOSE_DIR, "worker.err.log");
+  const errors = tail(errFile, 15);
+  if (errors) {
+    console.log(`\nErrors (last written ${lastWritten(errFile)}):\n${errors.replace(/^/gm, "  ")}`);
+  }
+  const logFile = join(GOOSE_DIR, "worker.log");
+  const log = tail(logFile, 15);
+  if (log) {
+    console.log(`\nActivity (last written ${lastWritten(logFile)}):\n${log.replace(/^/gm, "  ")}`);
+  }
+
+  if (stale) {
+    console.log("\nTo update:  npx --yes goosetools-worker@latest update\n");
+  } else if (!pid && installed) {
+    console.log("\nNot running. Restart it with:  npx --yes goosetools-worker@latest update\n");
+  } else {
+    console.log("");
+  }
+}

package/worker/skill.js

@@ -0,0 +1,26 @@
+// Splices sections out of skills/reference-analysis.md — the single source
+// of truth for the ref-analysis methodology shared by the style-gen,
+// drafting, and self-check prompts.
+
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const SKILL_PATH = join(
+  dirname(fileURLToPath(import.meta.url)),
+  "..",
+  "skills",
+  "reference-analysis.md",
+);
+
+let cached;
+
+export function skillSection(name) {
+  cached ??= readFileSync(SKILL_PATH, "utf8");
+  const re = new RegExp(
+    `<!-- SECTION: ${name} -->\\n([\\s\\S]*?)(?=<!-- SECTION: |$)`,
+  );
+  const m = cached.match(re);
+  if (!m) throw new Error(`skill section "${name}" not found in ${SKILL_PATH}`);
+  return m[1].trim();
+}

package/worker/style.js

@@ -0,0 +1,250 @@
+// Style generation — fulfills kind='style' jobs: the user's reference images
+// go in, a new styles/<slug>/ template set comes out, distilled by the local
+// Claude Code login. The style is PURELY the references — palette, fonts,
+// layout, composition, mood, motifs all come from them; the user's brand
+// only enters later, at render time, through placeholders like {{handle}}.
+
+import { runAgent } from "./agent-cli.js";
+import {
+  cpSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { extname, join } from "node:path";
+import yaml from "js-yaml";
+import { upload } from "@vercel/blob/client";
+import { skillSection } from "./skill.js";
+
+const RESERVED_SLUGS = new Set(["graph-paper", "polka-dot"]);
+const REQUIRED_TEMPLATES = ["cover", "text", "photo", "cta"];
+const MAX_FILE_BYTES = 20 * 1024;
+
+function stripFences(s) {
+  return s.replace(/^```(?:yaml)?\n?/m, "").replace(/\n?```\s*$/m, "").trim();
+}
+
+export function extFromUrl(url, contentType) {
+  const fromPath = extname(new URL(url).pathname).toLowerCase();
+  if ([".png", ".jpg", ".jpeg", ".webp"].includes(fromPath)) return fromPath;
+  return { "image/png": ".png", "image/jpeg": ".jpg", "image/webp": ".webp" }[contentType] ?? ".png";
+}
+
+function styleGenPrompt({ slug, refPaths, exemplar }) {
+  return `You are designing a reusable Instagram-carousel visual style for a slide-rendering engine.
+
+## Reference images — THE SOURCE OF TRUTH
+Read each of these image files and study them closely (they are in order — the first is the set's cover/pinned image):
+${refPaths.map((p) => `- ${p}`).join("\n")}
+
+### Step 1 — understand what the references are DOING (before any code)
+${skillSection("analyze")}
+
+The style you build must make it possible to create slides that DO the same thing, not just slides painted the same colors. If the references present color palettes, the style needs a template that renders labeled swatches. If they compare two things, the style needs a two-panel template. Purpose first, paint second.
+
+### Step 2 — reproduce their look faithfully
+Sample the ACTUAL colors from the reference images (background, text, accents) and use those as the style's palette via colors: overrides in style.yml; match their typography treatment (serif vs sans, italic, weight, case) with the closest Google Fonts via fonts: overrides; copy their layout, composition, spacing, and decorative motifs. A finished slide should look like it belongs in the same account as these references. The style is built ONLY from the references — no outside branding.
+
+## Engine contract (hard rules)
+- Slides are 1080x1350 (also rendered at 1:1 and 9:16 — use flexible layouts, no hardcoded heights). Each template is the inner HTML of a .slide div that already has {{style.padding}}px padding applied and position: relative.
+- Placeholders available in templates (substituted before render): {{colors.primary}} {{colors.primaryLight}} {{colors.primaryDark}} {{colors.accent}} {{colors.dark}} {{colors.lightBg}} {{colors.lightBorder}} {{colors.text}} {{colors.textOnLight}} {{fonts.heading}} {{fonts.headingWeight}} {{fonts.body}} {{fonts.mono}} {{style.radius}} {{text}} {{name}} {{subtitle}} {{photoSrc}} {{screenshotSrc}} {{handle}} {{gridBg}} {{ui}} {{swatches}} {{variant}}
+- {{swatches}} renders a slide's \`swatches: ["#hex", ...]\` list as <span class="swatch" style="background:#hex"><span class="swatch-label">#hex</span></span> elements — the template lays them out and styles .swatch / .swatch-label (size, shape, gaps, label typography). Use this to build palette-presentation templates when the references call for one.
+- {{variant}} renders as "flip" when a slide sets \`variant: flip\`, else as "". Every template whose layout has a movable overlay (a swatch stack, a badge column, a caption block anchored to one side) SHOULD support flipping: put {{variant}} in the root class list (e.g. <div class="slide xx-palette {{variant}}">) and define a .flip rule that mirrors the overlay to the opposite side (right:0 becomes left:0, text-align flips, etc.) so a slide can move the overlay off a photo's subject.
+- Beyond the required four templates you may add up to 4 more, NAMED FOR WHAT THEY DO (e.g. templates/palette.html, templates/compare.html, templates/list.html) whenever Step 1 found a content format the required templates can't express.
+- {{text}} arrives pre-rendered: *word* becomes <em> (style it as the color pop), _word_ becomes <i> (italic). Every template that shows {{text}} MUST style em and i.
+- {{gridBg}} is CSS declarations for the style's background (the engine builds it from style.yml) — use it as: style="position:absolute; inset:0; {{gridBg}}" on a background layer in light templates, or set your own flat background color.
+- Each template file is self-contained HTML with a <style> block scoped by unique class names. NO <script>. NO external URLs of any kind — fonts are injected by the engine, do not add font links or imports. NO gradients, ever — flat color or subtle pattern only.
+- Required template files: cover.html (bold opening hook), text.html (statement slide), photo.html (full-bleed {{photoSrc}} image with {{text}} caption), cta.html (closer with {{handle}}). Optionally also: light.html, resource.html (uses {{name}}, {{text}}, {{screenshotSrc}} as a site screenshot "receipt"), blue.html (flat brand-color pop slide) — include them if the references support those moods.
+- style.yml keys: name (the slug), optional background: dots (pale offset polka dots) — omit for graph-paper grid, optional fonts:{heading, headingWeight, mono} and colors:{...} overrides, notes (short description of the look).
+
+## Exemplar — an existing style that follows the contract
+--- style.yml ---
+${exemplar.styleYml}
+--- templates/cover.html ---
+${exemplar.cover}
+--- templates/text.html ---
+${exemplar.text}
+--- templates/cta.html ---
+${exemplar.cta}
+
+## Output format
+Return ONLY a single YAML document (no markdown fences, no prose, no commentary before or after) mapping relative filenames to complete file contents. THE VERY FIRST LINE of your reply must be exactly \`style.yml: |\` — do not describe the references or your plan first. Example shape:
+
+style.yml: |
+  name: ${slug}
+  ...
+templates/cover.html: |
+  ...
+templates/text.html: |
+  ...
+`;
+}
+
+const FILENAME_RE = /^(style\.yml|templates\/[a-z0-9-]+\.html)$/;
+
+// Claude sometimes narrates before the YAML ("The refs are ..."). Slice the
+// output down to the first real filename key, then drop any stray
+// commentary keys instead of failing the whole attempt on them.
+function extractFiles(stdout) {
+  const cleaned = stripFences(stdout);
+  const lines = cleaned.split("\n");
+  const start = lines.findIndex((l) =>
+    /^(style\.yml|templates\/[a-z0-9-]+\.html):/.test(l),
+  );
+  if (start === -1) throw new Error("no file mapping found in the output");
+  const parsed = yaml.load(lines.slice(start).join("\n"));
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error("output is not a filename→contents mapping");
+  }
+  const files = {};
+  for (const [k, v] of Object.entries(parsed)) {
+    if (FILENAME_RE.test(k)) files[k] = v;
+    else console.error(`  (dropping stray key "${String(k).slice(0, 60)}")`);
+  }
+  return files;
+}
+
+function validateStyleFiles(files) {
+  const names = Object.keys(files);
+  for (const f of names) {
+    if (typeof files[f] !== "string") throw new Error(`"${f}" is not a string`);
+    if (files[f].length > MAX_FILE_BYTES) throw new Error(`"${f}" is too large`);
+  }
+  if (!files["style.yml"]) throw new Error("style.yml missing");
+  const styleSpec = yaml.load(files["style.yml"]);
+  if (!styleSpec?.name) throw new Error("style.yml has no name");
+  for (const t of REQUIRED_TEMPLATES) {
+    if (!files[`templates/${t}.html`]) throw new Error(`templates/${t}.html missing`);
+  }
+  for (const [f, content] of Object.entries(files)) {
+    if (!f.startsWith("templates/")) continue;
+    if (!/\{\{(text|name)\}\}/.test(content)) {
+      throw new Error(`${f} uses neither {{text}} nor {{name}}`);
+    }
+    if (/<script/i.test(content)) throw new Error(`${f} contains a <script> tag`);
+    if (/https?:\/\//i.test(content)) throw new Error(`${f} references an external URL`);
+  }
+  return styleSpec;
+}
+
+export async function runStyleJob(job, { api, execFileAsync, ROOT, TOKEN, BASE_URL, writeBrandFile }) {
+  const { slug, name, refUrls } = job.newStyle ?? {};
+  if (!slug || !Array.isArray(refUrls) || refUrls.length === 0) {
+    throw new Error("Style job is missing its name or reference images");
+  }
+  console.log(`▶ style ${job.id}: "${name}" (${refUrls.length} refs) [${slug}]`);
+
+  if (RESERVED_SLUGS.has(slug)) throw new Error(`"${slug}" is a built-in style`);
+  const styleDir = join(ROOT, "styles", slug);
+  const marker = join(styleDir, ".generated");
+  if (existsSync(styleDir) && !existsSync(marker)) {
+    throw new Error(`A hand-made style already exists at styles/${slug} on this computer`);
+  }
+
+  const workDir = join(ROOT, "carousels", `style-${job.id.slice(0, 8)}`);
+  const refsDir = join(workDir, "refs");
+  mkdirSync(refsDir, { recursive: true });
+
+  const refPaths = [];
+  for (const [i, url] of refUrls.slice(0, 20).entries()) {
+    const res = await fetch(url);
+    if (!res.ok) throw new Error(`Reference download failed: ${url}`);
+    const ext = extFromUrl(url, res.headers.get("content-type"));
+    const p = join(refsDir, `ref-${String(i + 1).padStart(2, "0")}${ext}`);
+    writeFileSync(p, Buffer.from(await res.arrayBuffer()));
+    refPaths.push(p);
+  }
+
+  const exemplarDir = join(ROOT, "styles", "graph-paper");
+  const exemplar = {
+    styleYml: readFileSync(join(exemplarDir, "style.yml"), "utf8"),
+    cover: readFileSync(join(exemplarDir, "templates", "cover.html"), "utf8"),
+    text: readFileSync(join(exemplarDir, "templates", "text.html"), "utf8"),
+    cta: readFileSync(join(exemplarDir, "templates", "cta.html"), "utf8"),
+  };
+
+  let prompt = styleGenPrompt({ slug, refPaths, exemplar });
+  let files;
+  for (let attempt = 1; attempt <= 2; attempt++) {
+    // mode "read": the agent must look at the reference images under ROOT.
+    const { text: stdout } = await runAgent({
+      agent: job.agentCli,
+      prompt,
+      mode: "read",
+      cwd: ROOT,
+      timeoutMs: 15 * 60 * 1000,
+    });
+    try {
+      files = extractFiles(stdout);
+      validateStyleFiles(files);
+      // style.yml name must be the slug render.js will look up
+      const spec = yaml.load(files["style.yml"]);
+      if (spec.name !== slug) {
+        spec.name = slug;
+        files["style.yml"] = yaml.dump(spec);
+      }
+      break;
+    } catch (e) {
+      console.error(`Style attempt ${attempt} invalid: ${e.message}`);
+      if (attempt === 2) throw new Error(`Style generation failed: ${e.message}`);
+      prompt += `\n\nYour previous attempt was rejected: ${e.message}. Return the corrected full YAML document.`;
+    }
+  }
+
+  rmSync(styleDir, { recursive: true, force: true });
+  mkdirSync(join(styleDir, "templates"), { recursive: true });
+  for (const [f, content] of Object.entries(files)) {
+    writeFileSync(join(styleDir, f), content);
+  }
+  writeFileSync(marker, JSON.stringify({ jobId: job.id, generatedAt: new Date().toISOString() }));
+  // Keep the refs with the style — carousel jobs re-read them to draft and
+  // self-check against the originals. The manifest records which URLs (in
+  // order) these files came from so a stale cache can be detected.
+  cpSync(refsDir, join(styleDir, "refs"), { recursive: true });
+  writeFileSync(
+    join(styleDir, "refs", "manifest.json"),
+    JSON.stringify({ urls: refUrls.slice(0, 20) }, null, 2),
+  );
+  console.log(`  styles/${slug}/ written (${Object.keys(files).length} files + ${refPaths.length} refs)`);
+
+  // Preview: render the new style's cover + text slide with the user's brand.
+  const previewDir = join(workDir, "preview");
+  mkdirSync(previewDir, { recursive: true });
+  writeBrandFile(previewDir, job.brand);
+  writeFileSync(
+    join(previewDir, "slides.yml"),
+    yaml.dump({
+      style: slug,
+      slides: [
+        {
+          template: "cover",
+          text: "a headline\n*looks like this*",
+          subtitle: "sample slide — your words go here",
+        },
+        { template: "text", text: "body copy looks\n*like this*" },
+      ],
+    }),
+  );
+  const outDir = join(previewDir, "output");
+  await execFileAsync(
+    "node",
+    [join(ROOT, "src", "render.js"), previewDir, "--aspect", "4:5", "--out", outDir],
+    { maxBuffer: 10 * 1024 * 1024, timeout: 5 * 60 * 1000 },
+  );
+
+  const blob = await upload(
+    `carousel/style-previews/${job.id}/preview.png`,
+    readFileSync(join(outDir, "slide-01.png")),
+    {
+      access: "public",
+      handleUploadUrl: `${BASE_URL}/api/carousel/upload`,
+      clientPayload: JSON.stringify({ workerToken: TOKEN }),
+      contentType: "image/png",
+    },
+  );
+
+  await api("complete", { jobId: job.id, ok: true, previewUrl: blob.url });
+  console.log(`✓ style ${job.id}: "${name}" ready — preview uploaded`);
+}