@funpixel/tools 0.0.0-stage → 0.1.1

package/dist/commands/unity.js

@@ -0,0 +1,198 @@
+import { join } from 'node:path';
+import { listProcs, machineDir, ownerFromEnv, projectOfProc, sessionOf } from "../machine/procs.js";
+import { MAX_UNITY, POLL_MS, STALE_MINUTES, view, holderLine } from "../unity/queue.js";
+import { NOT_RUN, spawnUnity, unityRun } from "../unity/run.js";
+import { du, GC_DAYS, gcApply, gcPlan, human } from "../unity/gc.js";
+import { applyRefusal, DISK_BELOW_GB, DISK_DAYS, diskApply, diskReport, KINDS, realDiskDeps, tilde } from "../unity/disk.js";
+import { ui } from "../ui.js";
+export const unityLocks = (env = process.env) => join(machineDir(env), 'unity-locks');
+const realSleep = (ms) => new Promise((r) => setTimeout(r, ms));
+const realBeat = (ms) => new Promise((r) => setTimeout(r, ms).unref());
+export function realRunDeps(io, env = process.env) {
+    return {
+        root: unityLocks(env), procs: listProcs, now: Date.now, sleep: realSleep, beat: realBeat,
+        log: (l) => io.error(`funtools unity: ${l}`), spawn: spawnUnity, env,
+        session: sessionOf(env, ownerFromEnv(env) ?? process.ppid), self: process.pid, heartbeatMs: 10_000,
+    };
+}
+const envNumber = (v) => (v && /^\d+(\.\d+)?$/.test(v) ? Number(v) : undefined);
+export async function unity(o, io, deps) {
+    const u = ui(io, 'unity');
+    const env = deps?.env ?? process.env;
+    const staleMinutes = o.staleMinutes ?? envNumber(env.FUNTOOLS_UNITY_STALE_MINUTES) ?? STALE_MINUTES;
+    const max = o.max ?? envNumber(env.FUNTOOLS_UNITY_MAX) ?? MAX_UNITY;
+    if (!(max >= 1) || !Number.isInteger(max)) {
+        u.error(`--max ${max}`, 'a whole number of Unity runs, 1 or more');
+        return NOT_RUN;
+    }
+    if (!(staleMinutes > 0)) {
+        u.error(`--stale-minutes ${staleMinutes}`, 'minutes without progress before a lock is reclaimed, above 0');
+        return NOT_RUN;
+    }
+    const d = { ...realRunDeps(io, env), ...deps };
+    const staleMs = staleMinutes * 60_000;
+    switch (o.sub) {
+        case 'run': {
+            if (!o.unityArgs.length) {
+                u.error('nothing to run', 'funtools unity run -- -executeMethod Setup.Configure (Unity\'s arguments after --)');
+                return NOT_RUN;
+            }
+            const r = await unityRun({
+                unityArgs: o.unityArgs, project: o.project, unity: o.unity, log: o.log, noQuit: o.noQuit, cwd: process.cwd(),
+                queue: { staleMs, max, pollMs: POLL_MS, maxWaitMs: o.maxWaitMinutes === undefined ? null : o.maxWaitMinutes * 60_000 },
+            }, d);
+            if (r.message)
+                u.error(r.message);
+            for (const e of r.errors ?? [])
+                io.error(`  ${e}`);
+            if (r.code !== NOT_RUN || r.project)
+                io.error(`funtools unity: exit ${r.code}${r.log ? ` (log: ${r.log})` : ''}`);
+            return r.code;
+        }
+        case 'jobs': {
+            const now = d.now();
+            const v = await view(d.root, await d.procs(), now, staleMs);
+            if (o.json) {
+                io.log(JSON.stringify({ root: d.root, max, ...v }, null, 2));
+                return 0;
+            }
+            u.heading(`unity jobs · ${v.slots.length + v.foreign.length} of ${max} Unity runs on this Mac · ${d.root}`);
+            if (!v.projects.length && !v.foreign.length)
+                u.line('nothing running, nothing waiting');
+            for (const p of v.projects) {
+                if (p.holder)
+                    u.item(p.verdict?.live ? 'pass' : 'warn', `${p.holder.project}: ${holderLine(p.holder, now)}`, p.verdict?.live ? `log ${p.holder.log ?? '(stdout)'}` : `stale — ${p.verdict?.why}; the next job reclaims it`);
+                else
+                    u.item('note', `${p.key}: free`);
+                for (const [i, t] of p.waiting.entries())
+                    u.line(`${i + 1}. waiting: session ${t.session}, pid ${t.pid}, \`${t.command}\``, 2);
+            }
+            for (const f of v.foreign)
+                u.item('note', `Unity pid ${f.pid} on ${projectOfProc(f) ?? '(project unknown)'}, not a funtools job: ${f.args.slice(0, 140)}`, 'counted against the cap, never stopped');
+            return 0;
+        }
+        case 'gc': {
+            if (o.disk)
+                return gcDisk(o, io, d, staleMs, deps?.disk);
+            if (o.apply || o.only !== undefined || o.below !== undefined) {
+                u.error('--apply, --only and --below go with --disk', 'funtools unity gc --disk [--below 20] [--only worktrees --apply]');
+                return NOT_RUN;
+            }
+            const days = o.days ?? GC_DAYS;
+            if (!(days >= 0)) {
+                u.error(`--days ${days}`, 'days since anything in the folder was touched');
+                return NOT_RUN;
+            }
+            const g = { root: d.root, procs: d.procs, now: d.now, du: deps?.du ?? du, staleMs };
+            const roots = o.roots.length ? o.roots : [process.cwd()];
+            const plan = await gcPlan(roots, days, g);
+            if (!o.yes) {
+                if (o.json) {
+                    io.log(JSON.stringify({ dry_run: true, days, roots, ...plan }, null, 2));
+                    return 0;
+                }
+                u.heading(`unity gc · dry run · untouched ${days}+ days · ${roots.join(', ')}`);
+                for (const f of plan.folders)
+                    u.item('todo', `${human(f.bytes).padStart(8)}  ${f.path}`, `last touched ${f.touched.slice(0, 10)}`);
+                for (const s of plan.skipped)
+                    u.item('skip', s.project, s.why);
+                if (!plan.folders.length)
+                    u.line(`nothing idle for ${days} days${plan.recent ? ` (${plan.recent} folder(s) in use more recently)` : ''}`);
+                else
+                    u.summary('note', `${human(plan.bytes)} in ${plan.folders.length} folder(s) — Unity rebuilds them; delete with: funtools unity gc ${o.roots.join(' ')}${o.roots.length ? ' ' : ''}--days ${days} --yes`);
+                return 0;
+            }
+            const done = await gcApply(plan, g);
+            const freed = done.removed.reduce((t, f) => t + f.bytes, 0);
+            if (o.json) {
+                io.log(JSON.stringify({ dry_run: false, days, roots, removed: done.removed, kept: done.kept, skipped: plan.skipped, bytes: freed }, null, 2));
+                return 0;
+            }
+            u.heading(`unity gc · untouched ${days}+ days · ${roots.join(', ')}`);
+            for (const f of done.removed)
+                u.item('pass', `deleted ${f.path}`, human(f.bytes));
+            for (const s of [...plan.skipped, ...done.kept])
+                u.item('skip', s.project, s.why);
+            u.summary('pass', `${human(freed)} freed from ${done.removed.length} folder(s)`);
+            return 0;
+        }
+        default:
+            u.error(o.sub ? `unknown: unity ${o.sub}` : 'which one?', 'funtools unity run -- <args> | unity jobs | unity gc [roots…] [--yes] | unity bridge status|install|remove | unity editor <action> | unity probe | unity play | unity capture --all');
+            return NOT_RUN;
+    }
+}
+const VERDICT_STATUS = { safe: 'todo', 'in-use': 'skip', kept: 'skip', context: 'note', removed: 'pass', failed: 'warn' };
+async function gcDisk(o, io, d, staleMs, over) {
+    const u = ui(io, 'unity');
+    if (o.yes) {
+        u.error('--yes is for unity gc without --disk', 'funtools unity gc --disk --apply --only <kind>');
+        return NOT_RUN;
+    }
+    const below = o.below ?? DISK_BELOW_GB;
+    const days = o.days ?? DISK_DAYS;
+    if (!(below > 0)) {
+        u.error(`--below ${below}`, 'free gigabytes to warn under, above 0');
+        return NOT_RUN;
+    }
+    if (!(days >= 0)) {
+        u.error(`--days ${days}`, 'days since anything in the folder was touched');
+        return NOT_RUN;
+    }
+    let only = null;
+    if (o.only !== undefined) {
+        const ks = o.only.split(',').map((k) => k.trim()).filter(Boolean);
+        const bad = ks.filter((k) => !KINDS.includes(k));
+        if (bad.length || !ks.length) {
+            u.error(`--only ${o.only}`, `one or more of ${KINDS.join(', ')} (comma-separated)`);
+            return NOT_RUN;
+        }
+        only = ks;
+    }
+    const dd = realDiskDeps({ procs: d.procs, now: d.now, unityLocks: d.root, staleMs, env: d.env, ...over });
+    const opts = { below, days, roots: o.roots.length ? o.roots : [dd.cwd], only, apply: !!o.apply, strict: !!o.strict };
+    const refused = applyRefusal(opts);
+    if (refused) {
+        u.error(refused);
+        return NOT_RUN;
+    }
+    const r = opts.apply ? await diskApply(opts, dd) : await diskReport(opts, dd);
+    const code = r.below ? 1 : 0;
+    if (o.json) {
+        io.log(JSON.stringify(r, null, 2));
+        return code;
+    }
+    printDisk(r, opts, o.roots, dd.home, io);
+    return code;
+}
+function printDisk(r, o, given, home, io) {
+    const u = ui(io, 'unity');
+    const t = (p) => tilde(p, home);
+    const size = (b, atLeast) => (b === undefined ? '' : `${atLeast ? '≥' : ''}${human(b)}`).padStart(9);
+    const [free, ...rest] = r.lines;
+    u.heading(`unity gc --disk · ${o.apply ? `applying ${o.only.join(', ')}` : 'report only'} · untouched ${o.days}+ days · ${o.roots.map(t).join(', ')}`);
+    u.item(free.state === 'pass' ? 'pass' : free.state === 'fail' ? 'fail' : 'warn', free.says, free.next);
+    const groups = [
+        [o.apply ? 'Done' : 'Safe to reclaim, largest first', (v) => v === 'safe' || v === 'removed' || v === 'failed'],
+        ['In use or kept (never touched)', (v) => v === 'in-use' || v === 'kept'],
+        ['Context (sizes only, never touched)', (v) => v === 'context'],
+    ];
+    for (const [title, pick] of groups) {
+        const ls = rest.filter((l) => pick(l.verdict));
+        if (!ls.length)
+            continue;
+        u.heading(title);
+        for (const l of ls) {
+            u.item(VERDICT_STATUS[l.verdict] ?? 'note', `${size(l.bytes, l.at_least)}  ${l.check}`, l.says);
+            if (l.next)
+                u.line(`${l.verdict === 'safe' ? 'reclaim' : 'next'}: ${l.next}`, 2);
+        }
+    }
+    const safe = rest.filter((l) => l.verdict === 'safe');
+    const applyKinds = [...new Set(safe.filter((l) => l.applies).map((l) => l.kind))];
+    if (o.apply)
+        u.summary('pass', `${human(r.freed_bytes)} freed; ${human(r.free_bytes)} free now`);
+    else if (!safe.length)
+        u.summary(r.below ? (o.strict ? 'fail' : 'warn') : 'pass', `nothing provably safe to reclaim${r.below ? ' — look at the in-use and context lines above' : ''}`);
+    else
+        u.summary(r.below ? (o.strict ? 'fail' : 'warn') : 'note', `${human(r.reclaimable_bytes)} reclaimable in ${safe.length} item(s); nothing deleted${applyKinds.length ? ` — or let funtools do the ${applyKinds.join(', ')} part, re-checked first: funtools unity gc --disk ${given.map((g) => `${g} `).join('')}${o.days !== DISK_DAYS ? `--days ${o.days} ` : ''}--apply --only ${applyKinds.join(',')}` : ''}`);
+}

package/dist/commands/upgrade.js

@@ -0,0 +1,186 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { dirname, join, posix, resolve } from 'node:path';
+import { readManaged, sha, writeManaged } from "../managed.js";
+import { scaffoldFiles, TEMPLATES } from "./init.js";
+import { probeSkeleton } from "../sim/skeleton.js";
+import { guidanceHash, isGuidance } from "../guidance.js";
+import { currentVersion, latestNow, newer, selfUpdateCommand } from "../update.js";
+import { ui } from "../ui.js";
+function heldAs(dir) {
+    try {
+        return JSON.parse(readFileSync(join(dir, 'funpixel.json'), 'utf8')).metadata?.orientation === 'portrait' ? 'portrait' : 'landscape';
+    }
+    catch {
+        return 'landscape';
+    }
+}
+export async function upgrade(opts, io = console) {
+    const dir = resolve(opts.target ?? '.');
+    const u = ui(io, 'upgrade');
+    const managed = await readManaged(dir);
+    if (!managed.framework) {
+        u.error(`${dir} was not created by funtools init (no .funtools/managed.json)`, 'nothing to upgrade; `funtools doctor --add-hooks` adapts a foreign game');
+        return 3;
+    }
+    u.heading(`upgrade · ${dir}`);
+    const next = await scaffoldFiles(managed.framework, managed.name ?? '', heldAs(dir));
+    let updated = 0, kept = 0, added = 0, keptGuidance = 0, parked = 0, unchanged = 0;
+    const toAdd = [];
+    const notTheTemplates = new Set();
+    for (const [rel, text] of Object.entries(next)) {
+        const path = join(dir, rel);
+        const recorded = managed.files[rel];
+        const newHash = sha(text);
+        if (!existsSync(path)) {
+            if (recorded) {
+                notTheTemplates.add(rel);
+                continue;
+            }
+            toAdd.push(rel);
+            continue;
+        }
+        const current = sha((await readFile(path, 'utf8')).replace(/\r\n/g, '\n'));
+        if (current === newHash) {
+            managed.files[rel] = newHash;
+            continue;
+        }
+        if (current === recorded) {
+            await writeFile(path, text);
+            managed.files[rel] = newHash;
+            updated++;
+            u.item('pass', `updated ${rel}`);
+        }
+        else if (recorded === newHash) {
+            notTheTemplates.add(rel);
+            unchanged++;
+        }
+        else {
+            notTheTemplates.add(rel);
+            await writeFile(`${path}.funtools-new`, text);
+            kept++;
+            if (isGuidance(rel))
+                keptGuidance++;
+            u.item('warn', `kept yours: ${rel}`, `changed by you; merge ${rel}.funtools-new by hand`);
+        }
+    }
+    for (const rel of parkOrder(toAdd, next, notTheTemplates)) {
+        const path = join(dir, rel);
+        await mkdir(dirname(path), { recursive: true });
+        const on = notTheTemplates.has(rel) ? leansOn(rel, next[rel], next, notTheTemplates) : null;
+        if (on && rel === PROBES) {
+            await writeFile(`${path}.funtools-new`, probeSkeleton(dir));
+            parked++;
+            u.item('note', `probe skeleton for your rules parked: ${rel}.funtools-new`, `the kit's probe plays the demo's rules; this one imports yours and names the five places to fill — then \`funtools sim\` measures play length and the skill ceiling`);
+            continue;
+        }
+        if (on) {
+            await writeFile(`${path}.funtools-new`, next[rel]);
+            parked++;
+            u.item('note', `new kit module parked: ${rel}.funtools-new`, `it ${DESCRIBES[rel] === on ? 'describes' : 'imports'} ${on}, which you changed or removed; wire it in by hand if you want it`);
+            continue;
+        }
+        await writeFile(path, next[rel]);
+        managed.files[rel] = sha(next[rel]);
+        added++;
+        u.item('pass', `added ${rel}`);
+    }
+    await writeManaged(dir, managed);
+    if (kept || parked)
+        u.item('note', 'take what helps from the .funtools-new copies', '`funtools upgrade --discard` says no to the rest');
+    await recordGuidance(dir, keptGuidance, u);
+    u.summary('pass', `${updated} updated, ${added} added, ${kept} kept as yours${parked ? `, ${parked} new modules parked` : ''}${unchanged ? `, ${unchanged} of yours the kit has not changed` : ''}`);
+    return 0;
+}
+const PROBES = 'test/probes.ts';
+const DESCRIBES = { 'test/feel.json': 'src/rules.ts' };
+const IMPORT = /\bfrom\s+['"](\.{1,2}\/[^'"]+)['"]|\bimport\s*\(\s*['"](\.{1,2}\/[^'"]+)['"]\s*\)/g;
+function target(rel, spec, next) {
+    const base = posix.normalize(posix.join(posix.dirname(rel), spec));
+    for (const c of [base, `${base}.ts`, `${base}.tsx`, `${base}/index.ts`])
+        if (c in next)
+            return c;
+    return null;
+}
+function leansOn(rel, text, next, off) {
+    if (DESCRIBES[rel] && off.has(DESCRIBES[rel]))
+        return DESCRIBES[rel];
+    for (const m of text.matchAll(IMPORT)) {
+        const t = target(rel, m[1] ?? m[2], next);
+        if (t && off.has(t))
+            return t;
+    }
+    return null;
+}
+function parkOrder(toAdd, next, off) {
+    let grew = true;
+    while (grew) {
+        grew = false;
+        for (const rel of toAdd)
+            if (!off.has(rel) && leansOn(rel, next[rel], next, off)) {
+                off.add(rel);
+                grew = true;
+            }
+    }
+    return toAdd;
+}
+async function recordGuidance(dir, keptGuidance, u) {
+    const path = join(dir, 'funpixel.json');
+    if (!existsSync(path))
+        return;
+    let manifest;
+    try {
+        manifest = JSON.parse(await readFile(path, 'utf8'));
+    }
+    catch {
+        return;
+    }
+    const hash = guidanceHash(join(TEMPLATES, 'common'));
+    if (keptGuidance) {
+        u.item('note', `guidance_hash stays ${String(manifest.guidance_hash ?? 'unset')}`, 'merge the kept guidance files, then run upgrade again');
+        return;
+    }
+    if (manifest.guidance_hash === hash)
+        return;
+    manifest.guidance_hash = hash;
+    await writeFile(path, JSON.stringify(manifest, null, 2) + '\n');
+    u.item('pass', `guidance_hash ${hash}`, 'the agent guidance is this funtools\' GDK');
+}
+export async function discardOffers(opts, io = console) {
+    const dir = resolve(opts.target ?? '.');
+    const u = ui(io, 'upgrade');
+    const managed = await readManaged(dir);
+    if (!managed.framework) {
+        u.error(`${dir} was not created by funtools init (no .funtools/managed.json)`, 'nothing to discard');
+        return 3;
+    }
+    const next = await scaffoldFiles(managed.framework, managed.name ?? '', heldAs(dir));
+    let dropped = 0;
+    for (const [rel, text] of Object.entries(next)) {
+        const offer = join(dir, `${rel}.funtools-new`);
+        if (!existsSync(offer))
+            continue;
+        await rm(offer);
+        managed.files[rel] = sha(text);
+        dropped++;
+        u.item('pass', `discarded ${rel}.funtools-new`);
+    }
+    await writeManaged(dir, managed);
+    u.summary('pass', dropped ? `${dropped} kit offers discarded; yours stay as they are` : 'no .funtools-new waiting');
+    return 0;
+}
+export async function upgradeSelf(io = console, latest = latestNow) {
+    const u = ui(io, 'upgrade');
+    const current = currentVersion();
+    const found = await latest();
+    if (found === null)
+        u.item('note', `the npm registry did not answer with a funtools version (this is ${current})`);
+    else if (!newer(found, current)) {
+        u.summary('pass', `funtools ${current} is the newest`);
+        return 0;
+    }
+    else
+        u.item('note', `funtools ${found} is out (this is ${current})`);
+    u.summary('pass', `to update: ${selfUpdateCommand()}`);
+    return 0;
+}

package/dist/commands/variety.js

@@ -0,0 +1,108 @@
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { resolve } from 'node:path';
+import { EXIT } from "./verify.js";
+import { allMotifs, recordMotif } from "../lessons/motifs.js";
+import { closeOnes, compare, observed, SIGNALS } from "../variety/compare.js";
+import { cleanTitle, paletteOf, profileOf } from "../variety/profile.js";
+import { ui } from "../ui.js";
+import { designDoc } from "../gdd/doc.js";
+import { readPlaces } from "../variety/places.js";
+const LABEL = {
+    palette: 'palette', move: 'core verb + genre', titleScreen: 'title screen', motifs: 'motifs', title: 'title', hud: 'HUD dressing', wow: 'signature wow',
+};
+function profileFrom(m) {
+    if (existsSync(m.game)) {
+        const p = profileOf(m.game);
+        if (p)
+            return p;
+    }
+    return {
+        game: m.game, title: cleanTitle(m.title), genre: (m.genre ?? '').toLowerCase(), verb: m.verb ?? '',
+        palette: paletteOf(m.roles ?? {}, ''), nouns: m.nouns ?? [], stills: (m.stills ?? {}), wow: m.wow ?? null,
+    };
+}
+export async function variety(opts, io = console) {
+    const u = ui(io, 'variety');
+    const root = resolve(opts.target ?? '.');
+    if (opts.within)
+        return within(root, opts, io);
+    const home = opts.home ?? homedir();
+    const me = profileOf(root);
+    if (!me) {
+        if (opts.json)
+            io.log(JSON.stringify({ verdict: 'not_observed', reason: 'no design note' }, null, 2));
+        u.error('no design note to compare', 'write design/GDD.md first (skill funpixel-gdd); the palette, core verb and look come from it');
+        return EXIT.not_observed;
+    }
+    const byTitle = new Map();
+    let copies = 0;
+    for (const o of allMotifs(home).filter((m) => resolve(m.game) !== me.game).map(profileFrom)) {
+        const key = o.title.toLowerCase();
+        if (key === me.title.toLowerCase())
+            copies++;
+        else
+            byTitle.set(key, o);
+    }
+    const rows = [...byTitle.values()].map((o) => compare(me, o));
+    recordMotif(root, home, { verb: me.verb, stills: me.stills });
+    const close = rows.filter((c) => closeOnes(c).length).sort((a, b) => closeOnes(b).length - closeOnes(a).length);
+    const seen = SIGNALS.map((s) => ({ signal: s, compared: rows.filter((c) => c[s].state !== null).length, close: rows.filter((c) => c[s].state === 'close').length }));
+    const anyObserved = rows.some((c) => observed(c).length);
+    const verdict = !rows.length || !anyObserved ? 'not_observed' : close.length ? 'fail' : 'pass';
+    const declared = { verb: me.verb || null, genre: me.genre || null, palette: me.palette.length, title_screen: Object.keys(me.stills) };
+    if (opts.json) {
+        io.log(JSON.stringify({ verdict, game: me.title, declared, compared: rows.length, copies_skipped: copies, signals: seen, close: close.map(slim) }, null, 2));
+        return EXIT[verdict];
+    }
+    u.heading(`variety · ${me.title} against ${rows.length} other game(s) on this machine`);
+    u.line(`declared: verb ${me.verb || 'none'} · genre ${me.genre || 'none'} · ${me.palette.length} palette colour(s) · title capture ${declared.title_screen.join(', ') || 'none'}`, 0);
+    if (copies)
+        u.item('note', `${copies} other folder(s) of ${me.title} skipped (a copy is not another game)`);
+    for (const s of seen) {
+        if (!s.compared)
+            u.item('not_observed', `${LABEL[s.signal]}: not observed`, missing(s.signal, me));
+    }
+    for (const c of close) {
+        u.item('warn', `${c.other.title}${c.other.genre ? ` (${c.other.genre})` : ''}`, closeOnes(c).map((s) => `${LABEL[s]}: ${c[s].note}`).join(' · '));
+    }
+    if (verdict === 'not_observed') {
+        u.summary('not_observed', rows.length ? 'no signal both games declare — nothing was compared' : 'no other game on this machine to compare with yet (the kit records each game at the end of a session)');
+    }
+    else if (verdict === 'fail') {
+        u.summary('fail', `${close.length} game(s) too close — the choice is yours; a variety move (skill funpixel-gdd, references/design-note.md "Variety moves") is one way apart`);
+    }
+    else {
+        u.summary('pass', `apart from all ${rows.length}: ${seen.filter((s) => s.compared).map((s) => `${LABEL[s.signal]} ${s.compared}`).join(', ')} compared`);
+    }
+    return EXIT[verdict];
+}
+function within(root, opts, io) {
+    const u = ui(io, 'variety --within');
+    const r = readPlaces(root, designDoc(root)?.text ?? '');
+    if (opts.json) {
+        io.log(JSON.stringify(r, null, 2));
+        return r.verdict === 'not_observed' ? EXIT.not_observed : EXIT.pass;
+    }
+    u.heading(`variety --within · ${r.pictures.length} place picture(s)`);
+    for (const f of r.unreadable)
+        u.item('not_observed', `${f}: could not be read (PNG, or JPEG/WebP through sips or ffmpeg)`);
+    for (const p of r.pairs.filter((x) => x.alike))
+        u.item('warn', `${p.a} and ${p.b}`, p.why);
+    if (r.verdict !== 'not_observed')
+        u.line(`closest pair: ${[...r.pairs].sort((a, b) => a.colour - b.colour).slice(0, 1).map((p) => `${p.a} / ${p.b} (colour ΔE ${p.colour})`).join('')}`, 0);
+    u.summary(r.verdict === 'pass' ? 'pass' : r.verdict === 'warn' ? 'warn' : 'not_observed', r.why);
+    return r.verdict === 'not_observed' ? EXIT.not_observed : EXIT.pass;
+}
+const slim = (c) => ({ game: c.other.game, title: c.other.title, genre: c.other.genre, close: Object.fromEntries(closeOnes(c).map((s) => [s, { value: c[s].value, note: c[s].note }])) });
+function missing(signal, me) {
+    switch (signal) {
+        case 'palette': return me.palette.length < 3 ? 'this game declares under three colours: assets/style.json roles, or hex colours in the design note' : 'no other game declares three colours';
+        case 'move': return !me.verb || !me.genre ? 'declare "**Core verb:** <verb>" (or "you <verb> …" in the core loop) and metadata.genre in funpixel.json' : 'no other game declares both';
+        case 'titleScreen': return Object.keys(me.stills).length ? 'no other game has a title capture at the same viewport' : 'capture the title first: funtools capture --view title';
+        case 'motifs': return 'no motif nouns (the pitch, the 6-second ad, the look line)';
+        case 'title': return 'a title under four letters';
+        case 'hud': return me.hud ? 'no other game has a look --hud record' : 'measure the HUD first: funtools look --hud';
+        case 'wow': return me.wow ? 'no other game recorded a signature wow' : 'pick the signature first: funtools wow pick <id> --signature';
+    }
+}