@funpixel/tools 0.0.0-stage → 0.1.1

package/dist/commands/fidelity.js

@@ -0,0 +1,95 @@
+import { existsSync } from 'node:fs';
+import { basename, extname, join, resolve } from 'node:path';
+import { ui } from "../ui.js";
+import { references, referenceSize, renderLocal, scoreAll, weakest } from "../fidelity/run.js";
+const USAGE = 'funtools fidelity <model.glb> name=ref.png [name=ref.png …]';
+export async function fidelity(c, io = console) {
+    const u = ui(io, 'fidelity');
+    const [first, ...rest] = c.positionals;
+    const model = first && !first.includes('=') ? first : undefined;
+    const refs = references(model ? rest : c.positionals);
+    if (typeof refs === 'string') {
+        u.error(refs, `usage: ${USAGE}`);
+        return 3;
+    }
+    if (!model && !c.renders) {
+        u.error('no model and no renders', `usage: ${USAGE}, or --renders <dir> with views already made`);
+        return 3;
+    }
+    if (model && !existsSync(model)) {
+        u.error(`no such file: ${model}`, 'give the .glb (or .gltf/.fbx) to score');
+        return 3;
+    }
+    if (c.ownAxes && c.roll) {
+        u.error('--roll turns the squared model', 'drop --own-axes or --roll');
+        return 3;
+    }
+    const min = c.min === undefined ? undefined : Number(c.min);
+    if (min !== undefined && !(min >= 0 && min <= 100)) {
+        u.error(`--min ${c.min}`, '--min is a score 0-100, e.g. --min 95');
+        return 3;
+    }
+    let size = null;
+    if (c.size !== undefined) {
+        size = Number(c.size);
+        if (!Number.isInteger(size) || size < 256 || size > 1024) {
+            u.error(`--size ${c.size}`, '--size is 256-1024 px (default: the references\' own size)');
+            return 3;
+        }
+    }
+    const stem = model ? basename(model, extname(model)) : basename(resolve(c.renders));
+    const out = resolve(c.out ?? join(process.cwd(), '.funtools', 'fidelity', stem));
+    const opts = { renders: c.renders, out, ownAxes: c.ownAxes, roll: c.roll, outline: c.outline, quarterTurns: c.quarterTurns, sameScale: c.sameScale };
+    let dir = c.renders ? resolve(c.renders) : join(out, 'renders');
+    try {
+        if (!c.renders) {
+            size ??= await referenceSize(refs);
+            if (!c.json)
+                u.item('note', `rendering ${model} at ${size} px on your Blender (${c.ownAxes ? 'its own axes, 24' : 'squared to its axes, 48'} views; minutes for a big mesh)`);
+            const why = await renderLocal(model, dir, { ...opts, size });
+            if (why) {
+                u.error(`could not render ${model}`, why);
+                return 3;
+            }
+        }
+        else if (!existsSync(dir)) {
+            u.error(`no such folder: ${c.renders}`, 'give the folder of rendered views');
+            return 3;
+        }
+        const r = await scoreAll(model ?? null, dir, refs, opts, size);
+        return report(u, r, out, min, c.json, io);
+    }
+    catch (e) {
+        u.error(e instanceof Error ? e.message : String(e), 'check the pictures are PNG, JPEG or WebP');
+        return 3;
+    }
+}
+function report(u, r, out, min, json, io) {
+    const scored = Object.values(r.views).filter(Boolean);
+    const under = Object.entries(r.views).filter(([, v]) => v && min !== undefined && v.total < min).map(([n]) => n);
+    const code = scored.length === 0 ? 2 : under.length ? 1 : 0;
+    if (json) {
+        io.log(JSON.stringify({ ...r, out, min: min ?? null }, null, 2));
+        return code;
+    }
+    u.heading(`fidelity · ${r.model ?? r.renders}`);
+    for (const [name, v] of Object.entries(r.views)) {
+        if (!v) {
+            u.item('not_observed', `${name}: no shape found in the picture (it needs a plain ground)`);
+            continue;
+        }
+        u.item(min !== undefined && v.total < min ? 'fail' : 'pass', `${name} ${v.total}%  silhouette ${v.silhouette} · palette ${v.palette} (ΔE ${v.palette_dE}) · structure ${v.structure} · lines ${v.lines}`, `matched ${v.view} nudged ${v.nudge_deg}°${v.total < 95 ? `; ${weakest(v)}` : ''}`);
+    }
+    const c = r.consistency;
+    for (const f of c.findings)
+        u.item('warn', `references disagree (${f.check}): ${f.says}`, 'no one object matches them all: redraw the views from one master, or paint over one mesh\'s renders (funpixel-3d)');
+    if (!c.checked.length)
+        u.item('note', 'the references were not checked against one another: no two of them share an axis the cameras could place');
+    else if (!c.findings.length)
+        u.item('note', `the references agree (${c.checked.join(', ')}${c.checked.includes('extents') ? '' : '; --same-scale also compares sizes on one sheet'})`);
+    if (c.unplaced.length)
+        u.line(`not placed for that check: ${c.unplaced.join(', ')}`, 2);
+    u.line(`scores.json and a sheet per view in ${out}`, 1);
+    u.summary(code === 0 ? 'pass' : code === 1 ? 'fail' : 'not_observed', r.mean === null ? 'no view could be scored' : `mean ${r.mean}% over ${scored.length} view(s)${min !== undefined ? `; ${under.length ? `${under.join(', ')} under ${min}` : `all at ${min} or above`}` : ''}`);
+    return code;
+}

package/dist/commands/find.js

@@ -0,0 +1,116 @@
+import { join } from 'node:path';
+import { TEMPLATES } from "./init.js";
+import { COMMAND_KEYWORDS } from "../find/keywords.js";
+import { readSkillDescriptions, router, words } from "../find/route.js";
+import { CLAUDE_PLUGIN, claudeSkillName, formerNamesOf, formerSkill } from "../find/names.js";
+import { detectHost } from "../doctor/host.js";
+import { ui } from "../ui.js";
+export { words } from "../find/route.js";
+export function skills(root = join(TEMPLATES, 'common', '.agents', 'skills')) {
+    return readSkillDescriptions(root).map((s) => ({ kind: 'skill', name: s.name, says: s.description }));
+}
+export function rankSkills(ask, entries) {
+    const says = new Map(entries.map((e) => [e.name, e.says]));
+    return router(entries.map((e) => ({ name: e.name, description: e.says, formerly: formerNamesOf(e.name) })))(ask)
+        .filter((r) => r.score > 0 && r.matched.length > 0)
+        .map((r) => ({ kind: 'skill', name: r.skill, says: says.get(r.skill) ?? '', score: Math.round(r.score * 100) / 100, matched: r.matched }));
+}
+export function commands(usage, names = Object.keys(COMMAND_KEYWORDS)) {
+    const [synopsisBlock = '', described = ''] = usage.split('\n\n');
+    const syn = new Map();
+    let open = null;
+    for (const line of synopsisBlock.split('\n')) {
+        const head = /^ {2}funtools ([a-z][a-z0-9-]*)\b(.*)$/.exec(line);
+        if (head) {
+            open = head[1];
+            syn.set(open, [...(syn.get(open) ?? []), line.trim()]);
+            continue;
+        }
+        if (open && /^ {4,}\S/.test(line))
+            syn.get(open).push(line.trim());
+        else
+            open = null;
+    }
+    const heads = new Map(), paragraphs = new Map();
+    let para = null;
+    for (const line of described.split('\n')) {
+        const m = /^ {2}([a-z][a-z0-9-]*) +(\S.*)$/.exec(line);
+        if (m) {
+            para = heads.has(m[1]) ? null : m[1];
+            if (para) {
+                heads.set(para, m[2].trim());
+                paragraphs.set(para, m[2].trim());
+            }
+            continue;
+        }
+        const more = /^ {5,}(\S.*)$/.exec(line);
+        if (para && more && !more[1].startsWith('funtools '))
+            paragraphs.set(para, `${paragraphs.get(para)} ${more[1]}`);
+        else
+            para = null;
+    }
+    return names.map((name) => ({
+        kind: 'command', name,
+        says: paragraphs.get(name) ?? (syn.get(name)?.[0] ?? `funtools ${name}`),
+        head: heads.get(name) ?? '',
+        synopsis: (syn.get(name) ?? []).join(' '),
+        keywords: COMMAND_KEYWORDS[name] ?? '',
+    }));
+}
+const NAMED = 2, SAID = 1;
+export function rankCommands(ask, entries) {
+    const asked = [...new Set(words(ask))];
+    if (!asked.length)
+        return [];
+    const bags = entries.map((e) => {
+        const strong = new Set([...words(e.name.replace(/-/g, ' ')), ...words(e.keywords)]);
+        const all = new Set([...strong, ...words(e.synopsis.replace(/funtools /g, ' ')), ...words(e.head)]);
+        return { e, strong, all };
+    });
+    const df = new Map();
+    for (const b of bags)
+        for (const w of b.all)
+            df.set(w, (df.get(w) ?? 0) + 1);
+    const idf = (w) => Math.log((bags.length + 1) / ((df.get(w) ?? 0) + 0.5));
+    return bags.map(({ e, strong, all }) => {
+        const matched = asked.filter((w) => all.has(w));
+        const score = matched.reduce((t, w) => t + idf(w) * (strong.has(w) ? NAMED : SAID), 0);
+        return { kind: 'command', name: e.name, says: e.says, score: Math.round(score * 100) / 100, matched };
+    }).filter((h) => h.score > 0).sort((a, b) => b.score - a.score);
+}
+const short = (s, n = 150) => (s.length > n ? `${s.slice(0, n - 1).trimEnd()}…` : s);
+export async function find(opts, io = console) {
+    const u = ui(io, 'find');
+    if (!opts.ask.trim()) {
+        u.error('find needs words: what you want to do', 'funtools find "the jar sways too much"');
+        return 3;
+    }
+    const named = (opts.ask.toLowerCase().match(/(?:fp:|funpixel-)?[a-z0-9]+(?:-[a-z0-9]+)+|fp:[a-z0-9]+/g) ?? []).map(formerSkill);
+    const formerly = [...new Map(named.filter((f) => f !== null).map((f) => [f.was, f])).values()];
+    const skillHits = rankSkills(opts.ask, skills()).slice(0, 3);
+    for (const f of formerly)
+        if (!skillHits.some((h) => h.name === f.now)) {
+            const now = skills().find((s) => s.name === f.now);
+            if (now)
+                skillHits.unshift({ ...now, kind: 'skill', score: 0, matched: [f.was] });
+        }
+    const commandHits = rankCommands(opts.ask, commands(opts.usage, opts.names)).slice(0, 5);
+    if (opts.json) {
+        io.log(JSON.stringify({ ask: opts.ask, skills: skillHits, commands: commandHits, ...(formerly.length ? { formerly } : {}) }, null, 2));
+        return skillHits.length || commandHits.length ? 0 : 2;
+    }
+    if (!skillHits.length && !commandHits.length) {
+        u.summary('fail', 'nothing in the kit matched those words: say what you want to do another way');
+        return 2;
+    }
+    u.heading(`find · "${short(opts.ask, 60)}"`);
+    const claude = detectHost(opts.env ?? process.env)?.host === 'claude';
+    for (const f of formerly)
+        u.item('note', `skill ${f.was} is now part of ${f.now}`, `its guidance is ${f.now}/${f.body}${claude ? ` (${CLAUDE_PLUGIN}:${claudeSkillName(f.now)} in Claude Code)` : ''}`);
+    for (const h of skillHits)
+        u.item('note', `skill ${h.name}${claude ? ` (${CLAUDE_PLUGIN}:${claudeSkillName(h.name)} in Claude Code)` : ''}`, `${short(h.says)} (matched: ${h.matched.join(', ')})`);
+    for (const h of commandHits)
+        u.item('note', `funtools ${h.name}`, `${short(h.says)} (matched: ${h.matched.join(', ')})`);
+    u.summary('note', 'read the skill first; the command does the step');
+    return 0;
+}

package/dist/commands/firstlook.js

@@ -0,0 +1,138 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { EXIT } from "./verify.js";
+import { firstLookSet, SET_FILE, SET_GROUPS } from "../firstlook/set.js";
+import { matchBar } from "../owner/match.js";
+import { ui } from "../ui.js";
+import { firstLookQuality, notchCheck } from "../firstlook/quality.js";
+import { worthGate, WORTH_TITLE } from "../gdd/worth.js";
+import { OPENING_STAGES, readPipeline } from "../pipeline/pipeline.js";
+import { renderStudies, STUDIES_FN, STUDIES_PAGE } from "../firstlook/render.js";
+export const FIRSTLOOK_SUBCOMMANDS = ['list', 'skip', 'need', 'render'];
+const T = 'npx @funpixel/tools';
+export function openingNow(p) {
+    const st = p?.stages.find((x) => OPENING_STAGES.includes(x.id) && x.status !== 'done' && x.status !== 'skipped');
+    return st ? { id: st.id, title: st.title } : null;
+}
+const OPENING_NOW = {
+    'key-look': 'two pictures first: the key art and the hero\'s reference sheet (ref-*.png), shown to the owner for their yes; then a first playable built from them. The worth read and the rest of this set come with the whole plan, after the owner has played it',
+    prototype: 'the first playable, built from the key art and the hero\'s sheet, played by the owner; the worth read and the rest of this set come with the whole plan, after they say it has potential',
+};
+export async function firstlook(o, io = console) {
+    const u = ui(io, 'firstlook');
+    const root = resolve(o.dir ?? (o.sub === 'list' || o.sub === 'render' ? o.args[0] : undefined) ?? '.');
+    if (!existsSync(join(root, 'funpixel.json'))) {
+        u.error(`${root} is not a game folder (no funpixel.json)`, '--dir <game>');
+        return EXIT.not_observed;
+    }
+    try {
+        if (o.sub === 'render')
+            return await render(root, o, u, io);
+        if (o.sub === 'skip' || o.sub === 'need') {
+            const [item, ...rest] = o.args;
+            const ids = firstLookSet(root).items.map((i) => i.id);
+            if (!item || !ids.includes(item)) {
+                u.error(item ? `no item ${item}` : 'which item?', `one of: ${ids.join(', ')}`);
+                return EXIT.error;
+            }
+            const file = join(root, SET_FILE);
+            let rec = {};
+            try {
+                rec = JSON.parse(readFileSync(file, 'utf8'));
+            }
+            catch { }
+            rec.skip ??= {};
+            if (o.sub === 'skip') {
+                if (o.by !== 'owner') {
+                    u.error('dropping an item of the first look is the owner\'s', 'firstlook skip <item> --by owner "<their words>"');
+                    return EXIT.fail;
+                }
+                const words = rest.join(' ').trim();
+                if (!words) {
+                    u.error('say why, in the owner\'s words', `firstlook skip ${item} --by owner "<why>"`);
+                    return EXIT.error;
+                }
+                rec.skip[item] = { by: 'owner', words: words.slice(0, 300), at: (o.now ?? new Date()).toISOString() };
+            }
+            else
+                delete rec.skip[item];
+            mkdirSync(dirname(file), { recursive: true });
+            writeFileSync(file, JSON.stringify(rec, null, 2) + '\n');
+            u.summary('pass', o.sub === 'skip' ? `${item} skipped for this game, on the owner's word` : `${item} is asked for again`);
+            return EXIT.pass;
+        }
+        matchBar(root, { now: o.now });
+        const s = firstLookSet(root);
+        const q = firstLookQuality(root);
+        const notch = o.noBrowser ? { check: 'notch', state: 'not_observed', says: 'skipped (--no-browser)', fix: '', files: [] } : await notchCheck(root);
+        const checks = [q.places.finding, q.animation, notch];
+        const failing = checks.filter((c) => c.state === 'fail');
+        const p = readPipeline(root);
+        const opening = openingNow(p);
+        const wg = !opening && p?.stages.some((x) => x.status !== 'skipped' && x.gates.some((g) => g.kind === 'worth')) ? worthGate(root) : null;
+        if (o.json) {
+            io.log(JSON.stringify({ ...s, quality: { places: q.places, animation: q.animation, notch }, worth: wg, opening }, null, 2));
+            return s.missing.length || failing.length ? EXIT.fail : EXIT.pass;
+        }
+        if (opening)
+            u.item('note', `now: ${opening.title} (the flow's ${opening.id} stage)`, OPENING_NOW[opening.id] ?? `the flow names the step: ${T} flow`);
+        if (wg && wg.state !== 'met')
+            u.item('warn', `${WORTH_TITLE} ${wg.says}`, `make no more of the first look's art until it is answered: ${wg.run}`);
+        u.heading(`the first-look set · ${s.tier} tier · world: ${s.world.world} (${s.world.why})`);
+        for (const g of SET_GROUPS) {
+            const its = s.items.filter((i) => i.group === g.id);
+            const sk = s.skippedGroups.find((x) => x.group === g.id);
+            if (!its.length && !sk)
+                continue;
+            u.heading(g.title);
+            if (sk)
+                u.item('skip', sk.why);
+            for (const i of its)
+                u.item(i.state === 'have' ? 'pass' : i.state === 'skipped' ? 'skip' : i.state === 'waiting' ? 'warn' : 'fail', `${i.title}`, i.state === 'missing' ? `${i.says} → ${i.closes}` : `${i.id}: ${i.says}`);
+        }
+        u.heading('The pictures, as pictures');
+        for (const c of checks)
+            u.item(c.state === 'pass' ? 'pass' : c.state === 'fail' ? 'fail' : 'not_observed', `${c.check}: ${c.says}`, c.state === 'fail' ? `fix: ${c.fix}` : undefined);
+        if (failing.length && !s.missing.length) {
+            u.summary('fail', `${failing.length} check${failing.length === 1 ? '' : 's'} on the pictures fail${failing.length === 1 ? 's' : ''}: ${failing.map((c) => c.check).join(', ')} (each fix above)`);
+            return EXIT.fail;
+        }
+        u.summary(s.missing.length ? 'fail' : 'pass', s.missing.length ? `${s.missing.length} of ${s.items.length} missing: the plan is not put to the owner until each is shown (or the owner skips it: firstlook skip <item> --by owner "<why>")` : `the whole game is on the Plan tab (${s.items.length} items)`);
+        return s.missing.length || failing.length ? EXIT.fail : EXIT.pass;
+    }
+    catch (e) {
+        u.error(e.message);
+        return EXIT.error;
+    }
+}
+async function render(root, o, u, io) {
+    const page = o.page ?? STUDIES_PAGE;
+    if (!existsSync(join(root, page))) {
+        u.error(`no ${page}: the page of studies the game's own draw code composes`, `write it: a module script that imports the game's draw code (src/…), composes each picture at the play framing (the key art, the hero's sheet as ref-<hero>, the frames) and sets window.${STUDIES_FN} = async () => ({ keyart: canvas.toDataURL('image/png'), … }); then ${T} firstlook render (skill funpixel-gdd, references/first-look.md, "Drawn in code")`);
+        return EXIT.error;
+    }
+    const r = await renderStudies(root, { page });
+    if (o.json) {
+        io.log(JSON.stringify({ tool: 'funtools', command: 'firstlook render', page, ...r }, null, 2));
+        return r.state === 'done' && !r.refused.length ? EXIT.pass : r.state === 'not_observed' ? EXIT.not_observed : r.state === 'error' && !r.written.length && !r.refused.length ? EXIT.error : EXIT.fail;
+    }
+    u.heading(`the first look, drawn in code · ${page}${r.served ? ` (served by ${r.served === 'vite' ? 'the game\'s Vite' : 'its files'})` : ''}`);
+    for (const w of r.written)
+        u.item('pass', w.file, `${w.width} × ${w.height}`);
+    for (const x of r.refused)
+        u.item('fail', `${x.name}: refused`, x.why);
+    if (r.state !== 'done' && r.logs.length)
+        for (const l of r.logs.slice(-8))
+            u.line(l, 1);
+    if (r.state === 'not_observed') {
+        u.summary('not_observed', `${r.says}: nothing rendered, never a pass`);
+        return EXIT.not_observed;
+    }
+    if (r.state === 'error' && !r.written.length && !r.refused.length) {
+        u.error(r.says);
+        return EXIT.error;
+    }
+    const ok = r.state === 'done' && !r.refused.length;
+    u.summary(ok ? 'pass' : 'fail', `${r.says}${r.refused.length ? `; ${r.refused.length} refused` : ''}. A study is a composition from the game's own drawing, staged at its moment, never a capture of play; show them in the chat like any first look`);
+    return ok ? EXIT.pass : EXIT.fail;
+}