@funpixel/tools 0.0.0-stage → 0.1.1

package/dist/commands/assets.js

@@ -0,0 +1,473 @@
+import { laneSpendRefusal } from "../lanes/where.js";
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { apiOptions, ApiError } from "../api/http.js";
+import { estimate } from "../api/jobs.js";
+import { fileAssetId, requestAsSent, runWave } from "../assets/gen.js";
+import { identityPass, redrawInBatch, refineModel, runOptimize, runSingle } from "../assets/steps.js";
+import { localRenderer } from "../assets/bakeoff.js";
+import { assetCounts, countsLine, readBudget, writeBudget } from "../assets/counts.js";
+import { scriptManifest, writeScriptManifest } from "../assets/script.js";
+import { readCast } from "../cast/library.js";
+import { followJob, submit } from "../api/jobs.js";
+import { orphansOf, readLock, spend, writeLock } from "../assets/lock.js";
+import { isPicture, isSingle, MANIFEST, readAssetManifest, readStyle, STYLE } from "../assets/manifest.js";
+import { identityNotes, onlyMatches, planGen, REFS_SENT } from "../assets/plan.js";
+import { ART_DATA, processAssets, writeArtData } from "../assets/process.js";
+import { askYes, ui } from "../ui.js";
+import { explain } from "./gen.js";
+import { keyLeft } from "./account.js";
+import { checkTitle, gameTitle, titleNote } from "../gen/title.js";
+import { pixelsCmd } from "./assets-pixels.js";
+import { readPixelArt } from "../assets/pixelart.js";
+import { starterPlaceholders } from "../init/starters.js";
+export const ASSETS_EXIT = { ok: 0, changed: 1, refused: 2, error: 3 };
+export const CONFIRM_OVER = 50;
+export const SUBCOMMANDS = ['status', 'gen', 'regen', 'process', 'pixels', 'script', 'budget'];
+const MARK = { fresh: 'pass', stale: 'warn', missing: 'warn', rejected: 'fail', edited: 'warn', pending: 'note' };
+const list = (v) => (v ? v.split(',').map((s) => s.trim()).filter(Boolean) : undefined);
+const gameIdOf = (game) => {
+    try {
+        const g = JSON.parse(readFileSync(join(game, 'funpixel.json'), 'utf8')).game_id;
+        return typeof g === 'string' && /^[0-9a-f]{32}$/.test(g) ? g : undefined;
+    }
+    catch {
+        return undefined;
+    }
+};
+export async function assets(o, io = console) {
+    const u = ui(io, `assets ${o.sub}`);
+    const game = resolve(o.dir ?? '.');
+    try {
+        switch (o.sub) {
+            case 'status': return status(u, io, game, o);
+            case 'gen': return await gen(u, io, game, o);
+            case 'regen': return await regen(u, io, game, o);
+            case 'process': return await processCmd(u, io, game, o);
+            case 'pixels': return pixelsCmd(u, io, game, { args: o.args, snap: o.snap, json: o.json });
+            case 'script': return scriptCmd(u, io, game, o);
+            case 'budget': return budgetCmd(u, io, game, o);
+            default:
+                u.error(`unknown: assets ${o.sub}`, `use one of ${SUBCOMMANDS.join(', ')} (funtools assets --help)`);
+                return ASSETS_EXIT.error;
+        }
+    }
+    catch (e) {
+        const api = e instanceof ApiError ? explain(e) : null;
+        const m = e instanceof Error ? e.message : String(e), dash = m.indexOf(' — ');
+        const [what, next] = api ?? (dash < 0 ? [m, 'fix it and run again'] : [m.slice(0, dash), m.slice(dash + 3)]);
+        if (o.json)
+            io.log(JSON.stringify({ ok: false, error: { message: what, next } }, null, 2));
+        u.error(what, next);
+        return e instanceof ApiError && e.status === 402 ? ASSETS_EXIT.refused : ASSETS_EXIT.error;
+    }
+}
+function status(u, io, game, o) {
+    const items = readAssetManifest(game);
+    const lock = readLock(game);
+    const { statuses } = planGen(game, items, readStyle(game), lock);
+    const orphans = orphansOf(lock, items);
+    const money = spend(lock);
+    const counts = statuses.reduce((c, s) => ({ ...c, [s.state]: (c[s.state] ?? 0) + 1 }), {});
+    const todo = statuses.filter((s) => s.state !== 'fresh').length;
+    if (o.json) {
+        io.log(JSON.stringify({ ok: true, items: statuses, counts, orphans, credits: money }, null, 2));
+        return todo ? ASSETS_EXIT.changed : ASSETS_EXIT.ok;
+    }
+    u.heading(`assets · ${game}`);
+    for (const s of statuses)
+        u.item(MARK[s.state], `${s.name} — ${s.state} · ${s.kind}${s.family && s.family !== s.kind ? `/${s.family}` : ''}`, s.why);
+    for (const n of orphans)
+        u.item('note', `${n} — in the lock, not the manifest`, `its file (${lock.items[n].file ?? 'none'}) is yours to keep or delete`);
+    for (const n of identityNotes(planGen(game, items, readStyle(game), lock).all))
+        u.item('warn', n);
+    const fams = Object.entries(money.byFamily).map(([f, n]) => `${f} ${n}`).join(', ');
+    u.line(`credits spent: ${money.total}${fams ? ` (${fams})` : ''}`, 0);
+    const words = Object.entries(counts).map(([k, n]) => `${n} ${k}`).join(', ');
+    u.summary(todo ? 'warn' : 'pass', todo ? `${words} — \`funtools assets gen --dry-run\` shows what a run would make and cost` : `${words}`);
+    return todo ? ASSETS_EXIT.changed : ASSETS_EXIT.ok;
+}
+async function quote(api, todo) {
+    const per = new Map();
+    const notes = [];
+    if (!api)
+        return { per, total: null, notes: ['no API key: the estimate needs one (funtools login)'] };
+    let total = 0;
+    const cache = new Map();
+    for (const p of todo) {
+        let n = 0;
+        try {
+            for (const [i, s] of p.steps.entries()) {
+                const k = `${s.tool}:${JSON.stringify(s.input)}`;
+                const c = cache.get(k) ?? (await estimate(api, s.tool, s.input)).estimate_credits;
+                cache.set(k, c);
+                n += i === 0 ? c * p.serverNames.length : c;
+            }
+        }
+        catch (e) {
+            if (!(e instanceof ApiError))
+                throw e;
+            notes.push(`${p.item.name}: ${explain(e)[0]}`);
+            continue;
+        }
+        per.set(p.item.name, n);
+        total += n;
+    }
+    return { per, total, notes };
+}
+export function fitsIn(todo, per, left) {
+    const ready = todo.filter((p) => !p.waitsFor);
+    const order = [...ready.filter((p) => !isSingle(p.item.kind)), ...ready.filter((p) => isSingle(p.item.kind)), ...todo.filter((p) => p.waitsFor)];
+    const fits = [], refused = [];
+    let used = 0;
+    for (const p of order) {
+        const c = per.get(p.item.name);
+        if (c === undefined)
+            continue;
+        if (used + c <= left) {
+            fits.push(p.item.name);
+            used += c;
+        }
+        else
+            refused.push(p.item.name);
+    }
+    return { fits, refused, fitCredits: used };
+}
+function capOf(game, given) {
+    if (given !== undefined) {
+        const cap = Number(given);
+        if (!Number.isFinite(cap) || cap < 0)
+            throw new Error('--max-credits is a number of credits — e.g. --max-credits 200');
+        return { cap, from: '--max-credits' };
+    }
+    const b = readBudget(game);
+    return b ? { cap: b.credits, from: `the budget ${b.by} set (assets budget)` } : { cap: null, from: '' };
+}
+const PRICE_RETEXTURE = 42;
+export const BATCH_SIZE = 24;
+async function gen(u, io, game, o, regenFor) {
+    const items = readAssetManifest(game);
+    const style = readStyle(game);
+    const lock = readLock(game);
+    const filter = { only: list(o.only), family: o.family, staleOnly: o.stale, regen: regenFor ? new Set(regenFor.keys()) : undefined };
+    const unknown = filter.only?.filter((n) => !items.some((i) => onlyMatches([n], i.name)));
+    if (unknown?.length)
+        throw new Error(`not in ${MANIFEST}: ${unknown.join(', ')} — check the names (funtools assets status lists them)`);
+    let { todo, statuses } = planGen(game, items, style, lock, filter);
+    const api = apiOptions();
+    const cast = readCast(game);
+    if (!style && !o.json)
+        u.item('note', `no ${STYLE}: subjects are sent without a medium or family clause`);
+    if (!todo.length) {
+        const fresh = statuses.filter((s) => s.state === 'fresh').length;
+        if (o.json)
+            io.log(JSON.stringify({ ok: true, made: [], note: 'nothing to make' }, null, 2));
+        else
+            u.summary('pass', `nothing to make — ${fresh} of ${statuses.length} fresh${filter.only ? '; a fresh item is re-made with `assets regen <name> --because "…"`' : ''}`);
+        return ASSETS_EXIT.ok;
+    }
+    const batchSize = o.batch === undefined ? BATCH_SIZE : Number(o.batch);
+    if (!Number.isInteger(batchSize) || batchSize < 1 || batchSize > 32)
+        throw new Error('--batch is 1–32 items per generate_batch');
+    const q = await quote(api, todo);
+    const spent = spend(lock).total;
+    const { cap, from: capFrom } = capOf(game, o.maxCredits);
+    const left = api && q.total ? await keyLeft(api) : null;
+    const short = left && q.total !== null && q.total > left.least ? q.total - left.least : 0;
+    const shortLine = left && short ? `this run needs ~${q.total} credits and ${left.cap_left !== null && left.cap_left <= left.wallet ? `this key has ${left.cap_left} left under its monthly cap` : `the wallet holds ${left.wallet}`}: about ${short} short, so the last items will be refused` : '';
+    const fit = left && short ? fitsIn(todo, q.per, left.least) : null;
+    const unchecked = !!api && !!q.total && !left;
+    const castPics = todo.filter((p) => p.cast && isPicture(p.item.kind) && p.item.kind !== 'sheet' && p.item.identity !== 'off').length;
+    if (!o.json) {
+        u.heading(`assets gen · ${todo.length} item(s)${o.dryRun ? ' · dry run' : ''}`);
+        const title = gameTitle(game);
+        for (const p of todo) {
+            const draws = p.serverNames.length > 1 ? ` · ${p.serverNames.length} ${p.item.kind === 'model3d' ? 'candidates (bake-off)' : 'draws'}` : '';
+            const cost = q.per.has(p.item.name) ? ` · ~${q.per.get(p.item.name)} cr` : '';
+            const chain = p.steps.length > 1 ? ` → ${p.steps.slice(1).map((s) => s.tool).join(' → ')}` : '';
+            u.item(MARK[p.status.state], `${p.item.name} — ${p.status.state} · ${p.tool}${chain}${draws}${cost}${p.waitsFor ? ` · after ${p.waitsFor}` : ''}`, p.status.why);
+            if (typeof p.req.prompt === 'string')
+                u.line(`"${p.req.prompt.length > 160 ? `${p.req.prompt.slice(0, 157)}…` : p.req.prompt}"`, 2);
+            if (p.cast)
+                u.line(`cast: ${p.cast.card.id} — ${p.item.kind === 'pose' ? 'an edit of' : p.item.kind === 'model3d' ? 'made from' : p.item.kind === 'sheet' ? 'cut from' : 'drawn to'} ${p.cast.master}${p.cast.turnaround && p.references.some((r) => r.path === p.cast.turnaround) ? ' + its turnaround' : ''}`, 2);
+            if (p.references.length)
+                u.line(`drawn to: ${p.references.map((r) => `${r.path}${r.sha256 ? '' : r.item ? ` (made first by ${r.item})` : ' (not on disk)'}`).join(', ')}`, 2);
+            const named = isPicture(p.item.kind) && typeof p.req.prompt === 'string' ? checkTitle(p.req.prompt, title) : null;
+            if (named?.state === 'found')
+                u.item('warn', `${p.item.name}: ${titleNote(named, false).replace('pass --strip-title', `drop it from the item's subject or ${STYLE}`)}`);
+        }
+        for (const n of q.notes)
+            u.item('note', n);
+        const placeholders = (() => { try {
+            return starterPlaceholders(JSON.parse(readFileSync(join(game, MANIFEST), 'utf8')));
+        }
+        catch {
+            return [];
+        } })()
+            .filter((n) => todo.some((p) => p.item.name === n || p.item.name.startsWith(`${n}.`) || p.item.name.startsWith(`${n}-`)));
+        if (placeholders.length)
+            u.item('warn', `${placeholders.length} subject(s) still the starter's placeholders, written for its demo round and not this game: ${placeholders.join(', ')}`, `rewrite each "subject" in ${MANIFEST} for this game before generating`);
+        if (shortLine)
+            u.item('warn', shortLine, left.cap_left !== null && left.cap_left <= left.wallet ? 'raise the cap in Settings › Developers, or narrow the run with --only or --family' : 'add credits, or narrow the run with --only or --family');
+        if (fit)
+            u.line(`fits in the ${left.least} left: ${fit.fits.length ? `${fit.fits.join(', ')} (~${fit.fitCredits} cr)` : 'none'} · would be refused: ${fit.refused.join(', ')} (in the order a run sends them)`, 2);
+        if (unchecked)
+            u.item('note', `could not check what this key has left this month (its cap, the month's spend, the wallet): \`funtools budget\` shows it; the server refuses what the cap or the wallet cannot pay`, 'reading it needs a key with the usage:read scope (`funtools login` makes one with every scope)');
+        for (const n of identityNotes(todo))
+            u.item('warn', n);
+        if (todo.some((p) => p.references.length))
+            u.item('note', `references: ${REFS_SENT}`);
+        if (castPics)
+            u.item('note', `identity: ${castPics} picture(s) of the cast are held to their master after they land; a drifted one gets one targeted edit, then one redraw (each at about its own price), then is kept as the best and named`);
+        const batches = Math.ceil(todo.filter((p) => !isSingle(p.item.kind)).length / batchSize);
+        u.line(`estimate: ${q.total === null ? 'unknown' : `~${q.total} credits`}${batches > 1 ? ` in ${batches} batches of up to ${batchSize}` : ''} · spent so far ${spent}${cap !== null ? ` · cap ${cap} (${capFrom})` : ''}`, 0);
+    }
+    if (o.dryRun) {
+        if (o.json)
+            io.log(JSON.stringify({ ok: true, dry_run: true, items: todo.map((p) => ({ name: p.item.name, state: p.status.state, tool: p.tool, steps: p.steps.map((s) => s.tool), draws: p.serverNames.length, prompt: p.req.prompt, estimate_credits: q.per.get(p.item.name) ?? null, after: p.waitsFor ?? null, references: p.references, cast: p.cast?.card.id ?? null, source: p.source?.path ?? null })), identity: identityNotes(todo), estimate_credits: q.total, spent_credits: spent, cap, key_left_checked: !unchecked, key_left_credits: left?.cap_left ?? null, wallet_credits: left?.wallet ?? null, short_credits: short, fits: fit?.fits ?? null, would_be_refused: fit?.refused ?? null, batches: Math.ceil(todo.filter((p) => !isSingle(p.item.kind)).length / batchSize) }, null, 2));
+        else
+            u.summary('pass', 'dry run — nothing was sent; run it without --dry-run to make these');
+        return ASSETS_EXIT.ok;
+    }
+    if (!api)
+        throw new ApiError(401, 'no_key', 'no API key');
+    const est = q.total ?? 0;
+    const firstReady = todo.filter((p) => !p.waitsFor);
+    const firstBatch = firstReady.filter((p) => !isSingle(p.item.kind)).slice(0, batchSize);
+    const first = (firstBatch.length ? firstBatch : firstReady.slice(0, 1)).reduce((n, p) => n + (q.per.get(p.item.name) ?? 0), 0);
+    const capLabel = capFrom === '--max-credits' ? `--max-credits ${cap}` : `the asset budget of ${cap}`;
+    if (cap !== null && spent + first > cap) {
+        if (o.json)
+            io.log(JSON.stringify({ ok: false, code: 'over_cap', spent_credits: spent, estimate_credits: est, cap }, null, 2));
+        u.error(`this run (~${est}) would take the spend to ${spent + est}, over ${capLabel}`, 'raise the cap, or narrow the run with --only or --family');
+        return ASSETS_EXIT.refused;
+    }
+    const laneCap = laneSpendRefusal(game, est, 'assets gen');
+    if (laneCap) {
+        if (o.json)
+            io.log(JSON.stringify({ ok: false, code: 'lane_cap', estimate_credits: est, why: laneCap }, null, 2));
+        u.error(laneCap);
+        return ASSETS_EXIT.refused;
+    }
+    if (est > CONFIRM_OVER && !o.yes && !(await askYes(io, u, `about ${est} credits — run it?`))) {
+        if (o.json)
+            io.log(JSON.stringify({ ok: false, code: 'confirmation_required', estimate_credits: est }, null, 2));
+        u.error(`about ${est} credits, over the ${CONFIRM_OVER}-credit confirm line`, 'rerun with --yes to make them');
+        return ASSETS_EXIT.refused;
+    }
+    const gameId = gameIdOf(game);
+    const lockSheets = gameId && cast.size ? { sheets: await Promise.all([...cast.values()].map(async (m) => ({ name: `ref-${m.card.id}`, asset_id: await fileAssetId(api, game, m.master, `the cast master ${m.master}`) }))) } : undefined;
+    let pinned = false;
+    const render = o.render === undefined ? (() => { const r = localRenderer(); return typeof r === 'function' ? r : null; })() : o.render;
+    const results = [];
+    const identity = [];
+    const notes = [];
+    const progress = o.json ? null : u.progress();
+    let ran = spent;
+    const over = (n) => cap !== null && ran + n > cap;
+    const fixPrice = async (p) => (api && p.steps[0] ? (q.per.get(p.item.name) ?? 0) * 2 : 0);
+    const check = async (p) => {
+        if (p.item.kind === 'model3d' && p.cast && !over(PRICE_RETEXTURE)) {
+            const r = await refineModel(api, game, p, lock, render, { gameId });
+            ran += r.credits;
+            if (r.line)
+                notes.push(r.line);
+            const res = results.find((x) => x.name === p.item.name);
+            if (res)
+                res.credits += r.credits;
+        }
+        if (!p.cast || !isPicture(p.item.kind) || p.item.kind === 'sheet' || lock.items[p.item.name]?.verdict !== 'accept')
+            return;
+        const allow = !over(await fixPrice(p));
+        const r = await identityPass(api, game, p, lock, {
+            gameId,
+            redraw: async (pp) => {
+                if (!allow)
+                    return null;
+                if (pp.item.kind === 'pose') {
+                    const src = await fileAssetId(api, game, pp.source.path, `${pp.item.name}: its master`);
+                    const { job } = await submit(api, 'edit_image', { asset_id: src, prompt: pp.req.prompt, mode: 'pose', ...(gameId ? { game_id: gameId } : {}) }, { idempotencyKey: `fpx-asset:${pp.item.name}:${pp.hash}:identity-redraw`, confirm: true });
+                    return ['succeeded', 'failed', 'cancelled'].includes(job.status) ? job : followJob(api, job.job_id);
+                }
+                return redrawInBatch(api, game, pp, { confirm_cost: true, ...(gameId ? { game_id: gameId } : {}), item: await requestAsSent(api, game, pp) });
+            },
+            allowFix: allow,
+        });
+        if (r) {
+            identity.push(r);
+            ran += r.credits;
+        }
+    };
+    for (let wave = 0; todo.length && wave < 4; wave++) {
+        const ready = todo.filter((p) => !p.waitsFor);
+        if (!ready.length)
+            break;
+        const batched = ready.filter((p) => !isSingle(p.item.kind));
+        for (let i = 0; i < batched.length; i += batchSize) {
+            const chunk = batched.slice(i, i + batchSize);
+            const chunkEst = chunk.reduce((n, p) => n + (q.per.get(p.item.name) ?? 0), 0);
+            if (over(chunkEst)) {
+                for (const p of chunk)
+                    results.push({ name: p.item.name, outcome: 'refused', message: `over the cap: ${ran} spent + ~${chunkEst} for its batch > ${cap} — raise it (assets budget) and run again; made items are kept`, credits: 0, draws: 0, replayed: 0 });
+                continue;
+            }
+            progress?.update(`wave ${wave + 1}, batch ${i / batchSize + 1}: ${chunk.length} item(s) submitted, following their jobs`);
+            const made = await runWave(api, game, chunk, lock, { gameId, because: regenFor, ...(!pinned && lockSheets?.sheets.length ? { lock: lockSheets } : {}), render });
+            pinned = pinned || !!lockSheets?.sheets.length;
+            results.push(...made);
+            ran += made.reduce((n, r) => n + r.credits, 0);
+            for (const p of chunk)
+                await check(p);
+        }
+        for (const p of ready.filter((x) => isSingle(x.item.kind))) {
+            const est1 = q.per.get(p.item.name) ?? 0;
+            if (over(est1)) {
+                results.push({ name: p.item.name, outcome: 'refused', message: `over the cap: ${ran} spent + ~${est1} > ${cap}`, credits: 0, draws: 0, replayed: 0 });
+                continue;
+            }
+            progress?.update(`wave ${wave + 1}: ${p.item.name} (${p.steps.map((s) => s.tool).join(' → ') || 'local'})`);
+            const r = await runSingle(api, game, p, lock, { gameId });
+            results.push(r);
+            ran += r.credits;
+            await check(p);
+        }
+        for (const p of ready.filter((x) => x.item.optimize)) {
+            const r = await runOptimize(api, game, p, lock);
+            ran += r.credits;
+            const res = results.find((x) => x.name === p.item.name);
+            if (res)
+                res.credits += r.credits;
+            if (r.note)
+                notes.push(r.note);
+        }
+        const waiting = todo.filter((p) => p.waitsFor).map((p) => p.item.name);
+        if (!waiting.length)
+            break;
+        todo = [];
+        for (const p of planGen(game, items, style, lock, { only: waiting, regen: filter.regen }).todo) {
+            if (!p.waitsFor)
+                todo.push(p);
+            else
+                results.push({ name: p.item.name, outcome: 'refused', message: `waits for ${p.waitsFor}, which was not made`, credits: 0, draws: 0, replayed: 0 });
+        }
+    }
+    if (progress)
+        progress.done('note', `${results.length} item(s) settled`);
+    const charged = results.reduce((n, r) => n + r.credits, 0) + identity.reduce((n, r) => n + r.credits, 0);
+    const bad = results.filter((r) => r.outcome !== 'made');
+    const offModel = identity.filter((r) => r.verdict === 'off_model');
+    const counts = assetCounts(game);
+    if (o.json) {
+        io.log(JSON.stringify({ ok: !bad.length, results, identity, charged_credits: charged, spent_credits: spend(lock).total, counts, notes, pinned: pinned ? lockSheets?.sheets.map((s) => s.name) : [] }, null, 2));
+    }
+    else {
+        for (const r of results) {
+            const mark = r.outcome === 'made' ? 'pass' : r.outcome === 'refused' ? 'skip' : 'fail';
+            const extra = r.outcome === 'made' ? `${r.file} · ${r.credits} cr${r.draws > 1 ? ` · ${r.draws} draws (see .funtools/assets/draws/${r.name}/)` : ''}${r.replayed ? ` · ${r.replayed} job(s) collected, not paid again` : ''}` : r.message ?? r.outcome;
+            const fit = r.scores?.some((x) => x.palette !== null) ? ` · palette ${r.scores.length > 1 ? r.scores.map((x) => `d${x.draw} ${x.palette ?? '–'}%`).join(', ') + `, kept the best` : `${r.palette}%`}` : '';
+            u.item(mark, `${r.name} — ${r.outcome}`, extra + fit);
+            for (const l of r.bakeoff ?? [])
+                u.line(l, 2);
+            for (const w of r.warnings ?? [])
+                u.item('warn', w);
+        }
+        for (const r of identity) {
+            const how = r.rounds ? ` after ${r.rounds} fix round(s)` : '';
+            u.item(r.verdict === 'off_model' ? 'fail' : r.verdict === 'not_observed' ? 'note' : r.verdict === 'minor' ? 'warn' : 'pass', `${r.name} — ${r.verdict === 'off_model' ? 'OFF MODEL' : r.verdict} against ${r.cast}'s master${how}`, r.why.join('; ') || 'on model');
+        }
+        if (pinned)
+            u.item('note', `the cast's masters are pinned on the game's lock (${lockSheets.sheets.map((s) => s.name).join(', ')}): a hosted picture naming the game and a cast name is drawn to them`);
+        for (const n of notes)
+            u.item('warn', n);
+        if (results.some((r) => r.draws))
+            u.item('note', 'originals kept as sent under assets/raw/; every job is a line in assets/costs.jsonl');
+        if (offModel.length)
+            u.item('warn', `off model, named on the next card: ${offModel.map((r) => r.name).join(', ')} — \`judge identity\` for the features, or \`assets regen <name> --because "…"\``);
+        u.summary(bad.length || offModel.length ? 'warn' : 'pass', `${results.length - bad.length} made, ${bad.length} not — charged ${charged} credit(s), ${spend(lock).total} spent in all${counts ? ` · ${countsLine(counts)}` : ''}${bad.length ? '' : '; `assets process` sizes them for their roles'}`);
+    }
+    return bad.some((r) => r.outcome === 'refused') && bad.length === results.length ? ASSETS_EXIT.refused : bad.length || offModel.length ? ASSETS_EXIT.changed : ASSETS_EXIT.ok;
+}
+function scriptCmd(u, io, game, o) {
+    const plan = scriptManifest(game, o.from);
+    const byKind = plan.items.filter((i) => i.script).reduce((c, i) => ({ ...c, [i.kind]: (c[i.kind] ?? 0) + 1 }), {});
+    const scripted = plan.items.length - plan.kept;
+    if (o.write)
+        writeScriptManifest(game, plan);
+    if (o.json) {
+        io.log(JSON.stringify({ ok: true, source: plan.source, rows: plan.rows.length, items: scripted, kept: plan.kept, dropped: plan.dropped, by_kind: byKind, written: !!o.write }, null, 2));
+        return ASSETS_EXIT.ok;
+    }
+    u.heading(`assets script · ${plan.source}`);
+    for (const r of plan.rows) {
+        const n = plan.items.filter((i) => i.script === r.id);
+        u.item('note', `${r.id} — ${r.kind || 'picture'} × ${n.length}${r.cast ? ` · cast ${r.cast}` : ''}`, n.slice(0, 6).map((i) => i.name).join(', ') + (n.length > 6 ? `, … (${n.length})` : ''));
+    }
+    if (plan.dropped.length)
+        u.item('warn', `rows gone from the script, their items dropped: ${plan.dropped.join(', ')} (files on disk are kept)`);
+    for (const n of plan.notes ?? [])
+        u.item('warn', n);
+    u.line(Object.entries(byKind).map(([k, n]) => `${k} ${n}`).join(' · '), 0);
+    u.summary('pass', `${plan.rows.length} row(s) → ${scripted} item(s)${plan.kept ? `, ${plan.kept} hand-written kept` : ''}${o.write ? ` — written to ${MANIFEST}; \`assets gen --dry-run\` prices them` : ' — nothing written; --write puts them in the manifest'}`);
+    return ASSETS_EXIT.ok;
+}
+function budgetCmd(u, io, game, o) {
+    const [v] = o.args;
+    if (v === undefined) {
+        const b = readBudget(game);
+        const c = assetCounts(game);
+        if (o.json) {
+            io.log(JSON.stringify({ ok: true, budget: b, counts: c }, null, 2));
+            return ASSETS_EXIT.ok;
+        }
+        u.summary(b ? 'pass' : 'note', b ? `budget ${b.credits} credits, set by ${b.by} on ${b.at.slice(0, 10)}${c ? ` · ${countsLine(c)}` : ''}` : 'no asset budget — the owner sets one at the lock: funtools assets budget 400 --by owner');
+        return ASSETS_EXIT.ok;
+    }
+    const n = Number(v);
+    if (!Number.isInteger(n) || n < 0)
+        throw new Error('the budget is whole credits — funtools assets budget 400 --by owner');
+    const b = writeBudget(game, n, o.by?.trim() || 'agent');
+    if (o.json)
+        io.log(JSON.stringify({ ok: true, budget: b }, null, 2));
+    else
+        u.summary('pass', `asset budget ${b.credits} credits (by ${b.by}) — every assets gen keeps to it unless --max-credits says otherwise${b.by !== 'owner' ? '; the owner\'s own number is --by owner' : ''}`);
+    return ASSETS_EXIT.ok;
+}
+async function regen(u, io, game, o) {
+    const [name] = o.args;
+    if (!name)
+        throw new Error('name the item — funtools assets regen <name> --because "what was wrong"');
+    if (!o.because?.trim())
+        throw new Error(`say why it is re-made — funtools assets regen ${name} --because "the head came out normal-sized" (kept in the lock and in ${STYLE} failures, so the next prompt can learn from it)`);
+    if (!readAssetManifest(game).some((i) => i.name === name))
+        throw new Error(`${name} is not in ${MANIFEST} — check the name (funtools assets status)`);
+    if (!o.dryRun)
+        recordFailure(game, name, o.because.trim());
+    return gen(u, io, game, { ...o, only: name }, new Map([[name, o.because.trim()]]));
+}
+function recordFailure(game, asset, because) {
+    const p = join(game, STYLE);
+    if (!existsSync(p))
+        return;
+    const style = JSON.parse(readFileSync(p, 'utf8'));
+    style.failures = [...(Array.isArray(style.failures) ? style.failures : []), { asset, failure: because, at: new Date().toISOString().slice(0, 10) }];
+    writeFileSync(p, JSON.stringify(style, null, 2) + '\n');
+}
+async function processCmd(u, io, game, o) {
+    const items = readAssetManifest(game);
+    const lock = readLock(game);
+    const r = await processAssets(game, items, lock, { only: list(o.only), api: apiOptions(), gameId: gameIdOf(game), pixelArt: readPixelArt(game) });
+    await writeLock(game, lock);
+    const keep = new Set(items.filter((i) => lock.items[i.name]?.verdict === 'accept').map((i) => i.name));
+    const dataPath = writeArtData(game, r.data, keep);
+    if (o.json) {
+        io.log(JSON.stringify({ ok: true, results: r.results, notes: r.notes, data: ART_DATA, items: r.data }, null, 2));
+        return ASSETS_EXIT.ok;
+    }
+    u.heading(`assets process · ${game}`);
+    for (const p of r.results)
+        u.item(p.status === 'done' ? 'pass' : 'skip', p.name, p.status === 'done' ? (p.ops.join(', ') || 'already the right size') : p.note);
+    for (const n of r.notes)
+        u.item('note', n);
+    u.summary('pass', `${r.results.filter((p) => p.status === 'done').length} processed — data in ${dataPath.slice(game.length + 1)} (relative URLs, anchors, tints)`);
+    return ASSETS_EXIT.ok;
+}

package/dist/commands/beats.js

@@ -0,0 +1,77 @@
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import { writeFile } from 'node:fs/promises';
+import { join, relative, resolve } from 'node:path';
+import { EXIT } from "./verify.js";
+import { beatMap, readTrack } from "../sound/beats.js";
+import { ffmpegBin } from "../reel/encode.js";
+import { ui } from "../ui.js";
+const AUDIO = /\.(mp3|wav|ogg|m4a|aac|flac|webm)$/i;
+export const MUSIC_DIRS = ['public/music', 'assets/music', 'public/audio/music', 'src/assets/music', 'design/first-look/music'];
+function walk(p, out, depth = 0) {
+    if (!existsSync(p) || depth > 3)
+        return;
+    if (statSync(p).isFile()) {
+        if (AUDIO.test(p) && !out.includes(p))
+            out.push(p);
+        return;
+    }
+    for (const f of readdirSync(p).sort())
+        if (!f.startsWith('.') && f !== 'node_modules')
+            walk(join(p, f), out, depth + 1);
+}
+export const beatsFileOf = (track) => track.replace(/\.[a-z0-9]+$/i, '') + '.beats.json';
+export async function beats(opts, io = console) {
+    const u = ui(io, 'beats');
+    const root = resolve(opts.dir ?? '.');
+    const meter = opts.meter ?? 4;
+    if (!Number.isInteger(meter) || meter < 2 || meter > 12) {
+        u.error(`--meter ${meter}`, 'beats in a bar, 2 to 12 (4 for most music, 3 for a waltz)');
+        return EXIT.error;
+    }
+    const files = [];
+    for (const p of opts.paths.length ? opts.paths.map((x) => resolve(root, x)) : MUSIC_DIRS.map((d) => join(root, d)))
+        walk(p, files);
+    if (!files.length) {
+        if (opts.json)
+            io.log(JSON.stringify({ verdict: 'not_observed', reason: 'no music tracks' }, null, 2));
+        u.summary('not_observed', `no music found (${opts.paths.length ? opts.paths.join(', ') : MUSIC_DIRS.join(', ')})`);
+        return EXIT.not_observed;
+    }
+    const bin = ffmpegBin();
+    const rows = [];
+    for (const f of files) {
+        const rel = relative(root, f);
+        const t = readTrack(f, bin);
+        if (!t) {
+            rows.push({ file: rel, skipped: bin ? 'ffmpeg could not read it' : 'not a WAV, and no ffmpeg on PATH to read it' });
+            continue;
+        }
+        const map = beatMap(t.samples, t.rate, rel, meter);
+        const out = beatsFileOf(f);
+        await writeFile(out, JSON.stringify(map, null, 2) + '\n');
+        rows.push({ file: rel, out: relative(root, out), map });
+    }
+    const read = rows.filter((r) => r.map);
+    if (opts.json) {
+        io.log(JSON.stringify({ verdict: read.length ? 'pass' : 'not_observed', tracks: rows }, null, 2));
+        return read.length ? EXIT.pass : EXIT.not_observed;
+    }
+    u.heading(`beats · ${files.length} track(s)`);
+    for (const r of rows) {
+        if (!r.map) {
+            u.item('skip', r.file, r.skipped);
+            continue;
+        }
+        const m = r.map;
+        const weak = !m.detected || m.confidence < 0.35;
+        u.item(weak ? 'warn' : 'pass', r.file, m.detected
+            ? `${m.bpm} BPM, first beat ${m.offset.toFixed(3)} s, downbeat on beat ${m.downbeat + 1} of ${m.meter}, ${m.beats.length} beats, confidence ${m.confidence}${weak ? ' (a weak pulse: sync loosely, or to a track made with a clear one)' : ''} → ${r.out}`
+            : `no clear pulse: no tempo invented (an ambient bed; sync to events instead) → ${r.out}`);
+    }
+    if (!read.length) {
+        u.summary('not_observed', 'nothing read: install ffmpeg, or give WAV files');
+        return EXIT.not_observed;
+    }
+    u.summary('pass', `${read.length} beat map(s) written; read them in the game with src/beat.ts (loadBeats, beatAt, nearestBeat)`);
+    return EXIT.pass;
+}