@engenty/wizards-runtime 0.0.0-stage → 0.7.5

package/apps/runtime/dist/film/project.js

@@ -0,0 +1,257 @@
+import { createHash } from "node:crypto";
+import { existsSync } from "node:fs";
+import { cp, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { dirname, join, normalize } from "node:path";
+import { dataRef, FILM_SIZES } from "@engenty-wizards/shared/definition";
+import { gradientCss, ruleLines, textStyleLine } from "@engenty-wizards/shared/projects";
+import { unzipSync } from "fflate";
+import { logoSectionLine, renderTemplate, resolveRef } from "../engine/template.js";
+import { env } from "../env.js";
+import { getBlob } from "../files/blobs.js";
+import { extFor, loadAsset } from "../files/storage.js";
+import { projectFileContent } from "../services/project-files.js";
+import { placeSkills } from "./skills.js";
+import { soundCatalog } from "./sounds.js";
+import { runHyperframes } from "./tools.js";
+/**
+ * The folder a film is made in: one per run and step, kept after the run so a later change edits
+ * the code instead of starting over. Laid out for the client:
+ *
+ *   BRIEF.md            what to make (the step's brief, the format, the length)
+ *   CLAUDE.md, AGENTS.md the rules of the folder
+ *   .claude/skills/     the skill packages
+ *   showcase/           the wizard's style kit, the bar to reach
+ *   brand/              the space's brand: brand.json, logos
+ *   input/              what this run made before: voice lines, pictures, texts, uploads
+ *   audio-catalog/      the only sounds the film may use
+ *   film/               the HyperFrames project; renders/film.mp4 is the result
+ */
+export function filmRoot(runId, stepId) {
+    return join(env.dataDir, "films", runId, stepId);
+}
+const SESSION = join(".engenty", "session");
+export async function savedSession(root) {
+    try {
+        return (await readFile(join(root, SESSION), "utf8")).trim() || null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function saveSession(root, id) {
+    await mkdir(join(root, ".engenty"), { recursive: true });
+    await writeFile(join(root, SESSION), id);
+}
+/** Writes bytes to a path inside `root`; a name that would leave it is refused. */
+async function put(root, rel, data) {
+    const path = normalize(join(root, rel));
+    if (!path.startsWith(`${root}/`)) {
+        return;
+    }
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, data);
+}
+const safeName = (name) => name.replace(/[^A-Za-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "") || "file";
+function rules(step, skills) {
+    const size = FILM_SIZES[step.format];
+    return `# The film folder
+
+You make one film here, autonomously, to the end. Nobody answers questions: where a skill asks the
+person, decide yourself and note it in PROGRESS.md.
+
+- **What to make:** BRIEF.md. **The bar:** showcase/ (read showcase/SHOWCASE.md and showcase/frame.md
+  first when it exists, look at its stills, reuse its helpers from showcase/assets/). **The brand:**
+  brand/brand.json and brand/logos/ — colours, logo and fonts come from there only.
+- **Material:** input/ (see input/README.md). Use nothing from the web; you have no network.
+- **Skills:** ${skills.join(", ")} in .claude/skills/<name>/SKILL.md. Start with \`hyperframes\` and
+  read the skill files directly; do not update or install skills.
+- **The HyperFrames project is film/** (${size.width}×${size.height}, already set up). Keep every file
+  of the film inside film/.
+- **Running HyperFrames:** only through the \`hyperframes\` tool (MCP server \`film\`), e.g.
+  \`["lint","film"]\`, \`["check","film"]\`, \`["snapshot","film","--at","1,4,8"]\`,
+  \`["render","film","-q","draft"]\`, \`["transcribe","input/voice/l01.wav","--json","-d","input/voice"]\`.
+  \`npx\`, \`npm\` and network do not work in the shell.
+- **Look at your work:** snapshot the frames and read the PNGs, fix what is wrong. Before you finish,
+  render a draft and look at a frame every second of the whole film: empty areas, cut-off text,
+  overlaps, jumps.
+- **Finish** only when \`["check","film"]\` passes and \`["render","film","-q","draft"]\` succeeds, with \`film/index.html\` complete. The runtime renders the final MP4 itself.
+  End with a short summary: what the film shows, what you decided.
+
+## Sound (hard rules)
+
+- Sounds come only from audio-catalog/ (catalog.json lists each file with tags, keywords, licence).
+  Copy the picked files into film/assets/ and list them in film/AUDIO.md (file, source, licence, use).
+- Never generate, synthesize or download audio: no ffmpeg tone or noise, no TTS, no music models. Voice
+  lines come only from input/. Mixing is HyperFrames' job (\`<audio>\` with start, duration, volume).
+- Install nothing (no pip, brew, npm).
+`;
+}
+/** Sets up the folder for a first attempt; a later attempt finds it as it was left. */
+export async function prepareFilmFolder(step, ctx) {
+    const root = filmRoot(ctx.runId, step.id);
+    const brief = renderTemplate(step.brief, ctx.scope).trim();
+    // The same brief and material as last time: the film is there to go on with or to change.
+    const stamp = createHash("sha256")
+        .update(JSON.stringify([
+        brief,
+        Object.values(step.inputs).map((raw) => {
+            const ref = dataRef(raw);
+            const [head, id] = ref.split(".");
+            return head === "steps" ? ctx.state.outputs[id]?.at : ctx.state.values[ref];
+        }),
+    ]))
+        .digest("hex");
+    const stampFile = join(root, ".engenty", "inputs");
+    const same = existsSync(stampFile) && (await readFile(stampFile, "utf8")) === stamp;
+    if (same && existsSync(join(root, "film", "index.html")) && (await savedSession(root))) {
+        return { root, brief };
+    }
+    await rm(root, { recursive: true, force: true });
+    await mkdir(root, { recursive: true });
+    const skills = await placeSkills(step.skills, ctx.files, join(root, ".claude", "skills"));
+    const size = FILM_SIZES[step.format];
+    await put(root, "BRIEF.md", `# Brief\n\nFormat ${step.format}, ${size.width}×${size.height}${step.seconds ? `, about ${step.seconds} s` : ""}. Language of all text on screen: the brief's language.\n\n${brief}\n`);
+    const text = rules(step, skills);
+    await put(root, "CLAUDE.md", text);
+    await put(root, "AGENTS.md", text);
+    // The style kit.
+    if (step.kit) {
+        const file = ctx.files.find((f) => f.path === step.kit);
+        if (file) {
+            const entries = unzipSync(new Uint8Array(await getBlob(file.hash)));
+            for (const [name, data] of Object.entries(entries)) {
+                if (!name.endsWith("/")) {
+                    await put(join(root, "showcase"), name.replace(/^showcase\//, ""), data);
+                }
+            }
+        }
+    }
+    // The space's brand.
+    const b = ctx.scope.brand;
+    const logos = [];
+    const patterns = [];
+    for (const p of b.patterns ?? []) {
+        const f = ctx.projectFiles.find((x) => x.id === p.file);
+        try {
+            if (f) {
+                const { data } = await projectFileContent(f.projectId, f.id);
+                const name = `patterns/${safeName(f.name.replace(/\.[^.]+$/, ""))}.${extFor(f.mime) === "bin" ? (f.name.split(".").pop() ?? "bin") : extFor(f.mime)}`;
+                await put(join(root, "brand"), name, data);
+                patterns.push({
+                    file: name,
+                    name: p.name,
+                    ...(p.description ? { description: p.description } : {}),
+                    tile: Boolean(p.tile),
+                });
+            }
+        }
+        catch {
+            // a pattern less
+        }
+    }
+    for (const f of ctx.projectFiles.filter((p) => p.kind === "logo")) {
+        try {
+            const { data } = await projectFileContent(f.projectId, f.id);
+            const name = `logos/${safeName(f.name.replace(/\.[^.]+$/, ""))}.${extFor(f.mime) === "bin" ? (f.name.split(".").pop() ?? "bin") : extFor(f.mime)}`;
+            await put(join(root, "brand"), name, data);
+            const section = logoSectionLine(b.logoSections, f.id);
+            logos.push({
+                file: name,
+                ...(section ? { section } : {}),
+                ...(f.description ? { description: f.description } : {}),
+            });
+        }
+        catch {
+            // a logo less
+        }
+    }
+    await put(join(root, "brand"), "brand.json", JSON.stringify({
+        note: "The space's brand. Colours are named by what they are for; the first is the accent. A logo's section, a gradient's or a pattern's description says when to use it; colorRules, logoRules and typeRules, where there are any, say how colours, logos and type may be used; text is set in the fonts — a font with `uses` that leave out video is not used in a film: its text gets a system font.",
+        name: b.name ?? "",
+        about: b.about ?? "",
+        colors: (b.colors ?? []).map((c) => {
+            const s = b.colorSections?.find((x) => x.id === c.section);
+            return { name: c.name, value: c.value, ...(s ? { section: s.title } : {}) };
+        }),
+        ...(b.gradients?.length
+            ? {
+                gradients: b.gradients.map((g) => ({
+                    name: g.name,
+                    ...(g.description ? { description: g.description } : {}),
+                    section: b.colorSections?.find((x) => x.id === g.section)?.title,
+                    css: gradientCss(g),
+                })),
+            }
+            : {}),
+        ...(patterns.length ? { patterns } : {}),
+        logos,
+        ...(b.colorRules?.length ? { colorRules: ruleLines(b.colorRules).split("\n") } : {}),
+        ...(b.fonts?.length
+            ? {
+                fonts: b.fonts.map(({ family, role, weights, license, uses }) => ({
+                    family,
+                    role,
+                    weights,
+                    ...(license ? { license } : {}),
+                    ...(uses?.length ? { uses } : {}),
+                })),
+            }
+            : {}),
+        ...(b.textStyles?.length
+            ? {
+                textStyles: b.textStyles.map((s) => ({
+                    name: s.name,
+                    style: textStyleLine(s, b.fonts ?? []),
+                })),
+            }
+            : {}),
+        ...(b.typeRules?.length ? { typeRules: ruleLines(b.typeRules).split("\n") } : {}),
+        ...(b.logoRules?.length ? { logoRules: ruleLines(b.logoRules).split("\n") } : {}),
+        facts: (b.facts ?? []).map((f) => `${f.label}: ${f.value}`),
+    }, null, 1));
+    // What the run made before.
+    const listed = [];
+    for (const [name, raw] of Object.entries(step.inputs)) {
+        const ref = dataRef(raw);
+        const [head, id] = ref.split(".");
+        const output = head === "steps" ? ctx.state.outputs[id] : undefined;
+        const assetIds = head === "steps"
+            ? (output?.assets ?? []).map((a) => a.id)
+            : [ctx.state.values[ref]].flat().filter((v) => typeof v === "string");
+        let n = 0;
+        for (const assetId of assetIds) {
+            const found = await loadAsset(assetId);
+            if (found && found.row.runId === ctx.runId) {
+                const file = `${name}/${safeName(found.row.name)}`;
+                await put(join(root, "input"), file, found.data);
+                listed.push(`- \`input/${file}\` (${found.row.mime})`);
+                n++;
+            }
+        }
+        if (head === "steps" && output?.json !== undefined) {
+            await put(join(root, "input"), `${name}.json`, JSON.stringify(output.json, null, 1));
+            listed.push(`- \`input/${name}.json\``);
+        }
+        else if (head === "steps" && output?.text) {
+            await put(join(root, "input"), `${name}.md`, output.text);
+            listed.push(`- \`input/${name}.md\``);
+        }
+        else if (!n) {
+            const value = resolveRef(ref, ctx.scope);
+            if (value !== undefined && value !== null && value !== "") {
+                await put(join(root, "input"), `${name}.md`, typeof value === "string" ? value : JSON.stringify(value, null, 1));
+                listed.push(`- \`input/${name}.md\``);
+            }
+        }
+    }
+    await put(join(root, "input"), "README.md", `# Material for this film\n\n${listed.join("\n") || "(none)"}\n\nVoice lines play one after another in their order; their lengths decide the timing.\n`);
+    await cp(await soundCatalog(), join(root, "audio-catalog"), { recursive: true });
+    // The HyperFrames project, set up for the format.
+    const preset = { "16:9": "landscape", "9:16": "portrait", "1:1": "square" }[step.format];
+    const init = await runHyperframes(["init", "film", "--non-interactive", "--skip-transcribe", `--resolution=${preset}`], { cwd: root, signal: ctx.signal, timeoutMs: 5 * 60_000 });
+    if (init.code !== 0 || !existsSync(join(root, "film"))) {
+        throw new Error(`The film project could not be set up: ${init.out.slice(-300)}`);
+    }
+    await put(root, ".engenty/inputs", stamp);
+    return { root, brief };
+}

package/apps/runtime/dist/film/skills.js

@@ -0,0 +1,91 @@
+import { execFile } from "node:child_process";
+import { existsSync } from "node:fs";
+import { cp, mkdir, readdir, rename, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import { env } from "../env.js";
+import { getBlob } from "../files/blobs.js";
+const exec = promisify(execFile);
+export const PLATFORM_SKILLS = {
+    hyperframes: {
+        name: "hyperframes",
+        source: "https://github.com/heygen-com/hyperframes",
+        version: "6308727b85726433e6a1e148b608d8cb11085114",
+        licence: "Apache-2.0",
+        tarball: "https://codeload.github.com/heygen-com/hyperframes/tar.gz/6308727b85726433e6a1e148b608d8cb11085114",
+        folder: "skills",
+    },
+};
+const fetching = new Map();
+/** The folder holding a platform package's skills; fetched on first use. */
+export function platformSkills(name) {
+    const pkg = PLATFORM_SKILLS[name];
+    if (!pkg) {
+        return Promise.reject(new Error(`There is no skill package “${name}”.`));
+    }
+    const dir = join(env.dataDir, "skills", `${pkg.name}@${pkg.version.slice(0, 12)}`);
+    if (existsSync(join(dir, ".complete"))) {
+        return Promise.resolve(dir);
+    }
+    let pending = fetching.get(name);
+    if (!pending) {
+        pending = fetchPackage(pkg, dir).finally(() => fetching.delete(name));
+        fetching.set(name, pending);
+    }
+    return pending;
+}
+async function fetchPackage(pkg, dir) {
+    const res = await fetch(pkg.tarball);
+    if (!res.ok) {
+        throw new Error(`The skill package “${pkg.name}” could not be loaded (${res.status}).`);
+    }
+    const tmp = `${dir}.part`;
+    await rm(tmp, { recursive: true, force: true });
+    await mkdir(tmp, { recursive: true });
+    const archive = join(tmp, "package.tar.gz");
+    await writeFile(archive, Buffer.from(await res.arrayBuffer()));
+    // GitHub's tarball has one top folder (<repo>-<sha>); only its skills folder is kept.
+    await exec("tar", ["-xzf", archive, "-C", tmp, "--strip-components=1", `*/${pkg.folder}/*`]);
+    const skills = join(tmp, pkg.folder);
+    for (const entry of await readdir(skills, { withFileTypes: true })) {
+        if (!entry.isDirectory() || !existsSync(join(skills, entry.name, "SKILL.md"))) {
+            await rm(join(skills, entry.name), { recursive: true, force: true });
+        }
+    }
+    await writeFile(join(skills, "PACKAGE.json"), JSON.stringify({ name: pkg.name, source: pkg.source, version: pkg.version, licence: pkg.licence }, null, 1));
+    await writeFile(join(skills, ".complete"), new Date().toISOString());
+    await rm(dir, { recursive: true, force: true });
+    await rename(skills, dir);
+    await rm(tmp, { recursive: true, force: true });
+    return dir;
+}
+/**
+ * Puts the step's skill packages into `target` (one folder per skill): platform packages by
+ * name, workspace packages (`skills/<name>`) from the wizard's files. Returns the skill names.
+ */
+export async function placeSkills(names, files, target) {
+    await mkdir(target, { recursive: true });
+    const placed = [];
+    for (const name of names) {
+        if (name.startsWith("skills/")) {
+            const prefix = `${name.replace(/\/+$/, "")}/`;
+            const own = files.filter((f) => f.path.startsWith(prefix));
+            const skill = prefix.split("/")[1];
+            for (const f of own) {
+                const dest = join(target, skill, f.path.slice(prefix.length));
+                await mkdir(join(dest, ".."), { recursive: true });
+                await writeFile(dest, await getBlob(f.hash));
+            }
+            placed.push(skill);
+            continue;
+        }
+        const dir = await platformSkills(name);
+        for (const entry of await readdir(dir, { withFileTypes: true })) {
+            if (entry.isDirectory()) {
+                await cp(join(dir, entry.name), join(target, entry.name), { recursive: true });
+                placed.push(entry.name);
+            }
+        }
+    }
+    return placed;
+}

package/apps/runtime/dist/film/sounds.js

@@ -0,0 +1,122 @@
+import { existsSync } from "node:fs";
+import { cp, mkdir, readdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { env } from "../env.js";
+import { platformSkills } from "./skills.js";
+/**
+ * The sounds a film may use: nothing is generated, synthesized or downloaded by the client.
+ * soundcn (soundcn.xyz, MIT; the sounds by Kenney, CC0) for clicks, pops, impacts, jingles,
+ * switches, pages and paper; the effects HyperFrames ships with (whooshes, typing, risers).
+ * Fetched once into the data folder; `catalog.json` lists every file with tags and licence.
+ */
+const REGISTRY = "https://soundcn.xyz/r";
+/** soundcn categories that suit motion design; game noises (warcraft, laser, combat …) stay out. */
+const KEEP = new Set([
+    "ui",
+    "click",
+    "switch",
+    "select",
+    "maximize",
+    "minimize",
+    "book",
+    "card",
+    "cloth",
+    "scratch",
+    "scroll",
+    "drop",
+    "glass",
+    "jingles",
+    "pep",
+    "power",
+    "impact",
+    "chips",
+    "dice",
+    "error",
+    "round",
+    "zap",
+    "phase",
+    "low",
+    "metal",
+    "crafting",
+]);
+const CATALOG_VERSION = 1;
+const dir = join(env.dataDir, "catalogs", `sounds-v${CATALOG_VERSION}`);
+let building = null;
+/** The catalog folder (catalog.json + sfx/); built on first use. */
+export function soundCatalog() {
+    if (existsSync(join(dir, "catalog.json"))) {
+        return Promise.resolve(dir);
+    }
+    building ??= build().finally(() => {
+        building = null;
+    });
+    return building;
+}
+async function build() {
+    const tmp = `${dir}.part`;
+    await rm(tmp, { recursive: true, force: true });
+    await mkdir(join(tmp, "sfx"), { recursive: true });
+    const sounds = [];
+    const index = (await (await fetch(`${REGISTRY}/registry.json`)).json());
+    const picked = index.items.filter((i) => i.categories?.some((c) => KEEP.has(c)));
+    let next = 0;
+    const worker = async () => {
+        while (next < picked.length) {
+            const item = picked[next++];
+            try {
+                const res = await fetch(`${REGISTRY}/${item.name}.json`);
+                const json = (await res.json());
+                const m = json.files?.[0]?.content?.match(/data:audio\/(\w+);base64,([A-Za-z0-9+/=]+)/);
+                if (!m) {
+                    continue;
+                }
+                const ext = m[1] === "mpeg" ? "mp3" : m[1];
+                await writeFile(join(tmp, "sfx", `${item.name}.${ext}`), Buffer.from(m[2], "base64"));
+                sounds.push({
+                    file: `sfx/${item.name}.${ext}`,
+                    source: "soundcn",
+                    author: json.author ?? "Kenney",
+                    licence: item.meta?.license ?? "CC0",
+                    duration: item.meta?.duration,
+                    description: json.description,
+                    tags: item.categories?.concat(item.meta?.tags ?? []),
+                    keywords: item.meta?.keywords,
+                });
+            }
+            catch {
+                // one sound less
+            }
+        }
+    };
+    await Promise.all(Array.from({ length: 8 }, worker));
+    // The effects HyperFrames ships with its media skill.
+    const hf = join(await platformSkills("hyperframes"), "media-use", "audio", "assets", "sfx");
+    if (existsSync(hf)) {
+        for (const f of await readdir(hf)) {
+            if (f.endsWith(".mp3")) {
+                await cp(join(hf, f), join(tmp, "sfx", `hf-${f}`));
+                sounds.push({
+                    file: `sfx/hf-${f}`,
+                    source: "hyperframes",
+                    licence: "see CREDITS-hyperframes.md",
+                    description: f.replace(/\.mp3$/, "").replace(/-/g, " "),
+                });
+            }
+        }
+        if (existsSync(join(hf, "CREDITS.md"))) {
+            await writeFile(join(tmp, "CREDITS-hyperframes.md"), await readFile(join(hf, "CREDITS.md")));
+        }
+    }
+    if (!sounds.length) {
+        throw new Error("The sounds for films could not be loaded.");
+    }
+    sounds.sort((a, b) => a.file.localeCompare(b.file));
+    await writeFile(join(tmp, "catalog.json"), JSON.stringify({
+        note: "The only sounds this film may use. Never generate, synthesize or download audio.",
+        music: [],
+        sounds,
+    }, null, 1));
+    await rm(dir, { recursive: true, force: true });
+    await rename(tmp, dir);
+    return dir;
+}