@funpixel/tools 0.0.0-stage → 0.1.0

package/dist/commands/smoke-build.js

@@ -0,0 +1,305 @@
+import { spawnSync } from 'node:child_process';
+import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { EXIT } from "./verify.js";
+import { init } from "./init.js";
+import { apiOptions, sendJson } from "../api/http.js";
+import { getJob, TERMINAL } from "../api/jobs.js";
+import { apiKey } from "../keys/store.js";
+import { fingerprint } from "../verify/fingerprint.js";
+import { evaluateGate, readPipeline, worldRead } from "../pipeline/pipeline.js";
+import { worldHolds } from "../progress/holds.js";
+import { readProgress } from "../progress/progress.js";
+import { ui } from "../ui.js";
+export const SMOKE_RECORD = join('.funtools', 'smoke-build.json');
+const IMAGE = 'smoke-world', MODEL = 'smoke-model';
+const BIN = join(dirname(fileURLToPath(import.meta.url)), '..', 'bin.ts');
+export const realRunner = async (step, dir) => {
+    const node = (args) => spawnSync(process.execPath, [BIN, ...args], { cwd: dir, encoding: 'utf8', timeout: 10 * 60_000 });
+    if (step === 'scene')
+        return smokeState(node(['capture', dir, '--view', 'playing']));
+    const r = step === 'install' ? (existsSync(join(dir, 'node_modules')) ? { status: 0, stdout: 'installed', stderr: '' } : spawnSync('npm', ['install', '--no-audit', '--no-fund'], { cwd: dir, encoding: 'utf8', timeout: 10 * 60_000 }))
+        : step === 'build' ? spawnSync('npm', ['run', 'build'], { cwd: dir, encoding: 'utf8', timeout: 10 * 60_000 })
+            : step === 'capture' ? node(['capture', dir, '--view', 'playing'])
+                : step === 'world' ? node(['check', dir, '--world'])
+                    : step === 'score' ? node(['score', dir])
+                        : node(['progress', 'card', '--dir', dir, '--stage', 'slice', '--shot', 'last', '--line', 'smoke build: one locked picture and one generated model in the scene', '--spent', 'account']);
+    const said = `${r.stdout ?? ''}${r.stderr ?? ''}`.trim().split('\n').slice(-3).join(' · ');
+    return { ok: r.status === 0 || (step === 'world' && r.status !== 3), said };
+};
+export function smokeState(r) {
+    const out = `${r.stdout ?? ''}${r.stderr ?? ''}`;
+    const line = out.split('\n').find((l) => /^\s*state \{/.test(l));
+    let st = null;
+    try {
+        st = line ? JSON.parse(line.trim().slice('state '.length)) : null;
+    }
+    catch { }
+    if (!st)
+        return { ok: false, said: `the page published no state: ${out.trim().split('\n').slice(-2).join(' · ') || `capture exited ${r.status}`}` };
+    const model = st.smoke?.model;
+    return model === 'in scene'
+        ? { ok: true, said: `${MODEL} is in the live scene graph (found by name)` }
+        : { ok: false, said: `${MODEL} is not in the scene (the page says model: ${model ?? 'nothing'})` };
+}
+const readJson = (p) => { try {
+    return JSON.parse(readFileSync(p, 'utf8'));
+}
+catch {
+    return null;
+} };
+export const SMOKE_SCENE = `// Written by funtools smoke-build: the generated model and the locked-look picture, placed in the scene.
+import * as THREE from 'three';
+import { model, placeholders } from './models';
+
+export function placeSmoke(scene: THREE.Scene): void {
+  const smoke: Record<string, string> = { model: 'loading', picture: 'loading' };
+  Object.assign(window, { __FPX_SMOKE__: smoke });
+  new THREE.TextureLoader().load('/assets/images/${IMAGE}.png', (tex) => {
+    tex.colorSpace = THREE.SRGBColorSpace;
+    const back = new THREE.Mesh(new THREE.PlaneGeometry(16, 9), new THREE.MeshBasicMaterial({ map: tex }));
+    back.name = '${IMAGE}'; back.position.set(0, 4.5, -8);
+    scene.add(back);
+    smoke.picture = 'placed';
+  }, undefined, () => { smoke.picture = 'failed'; });
+  // The spine's loader (Draco, meshopt and KTX2, as the platform ships models). A model that fails to load
+  // stays out of the scene: nothing is drawn in its place.
+  model('${MODEL}', 2, () => new THREE.Group()).then((make) => {
+    if (placeholders.has('${MODEL}')) { smoke.model = 'failed'; return; }
+    const m = make(); m.name = '${MODEL}';
+    scene.add(m);
+    // The verdict reads the scene graph itself, not this script's word.
+    smoke.model = scene.getObjectByName('${MODEL}') ? 'in scene' : 'missing';
+  }, () => { smoke.model = 'failed'; });
+}
+`;
+export function wireScene(dir) {
+    const game = join(dir, 'src', 'game.ts');
+    let text = '';
+    try {
+        text = readFileSync(game, 'utf8');
+    }
+    catch {
+        return false;
+    }
+    if (!existsSync(join(dir, 'src', 'models.ts')))
+        return false;
+    writeFileSync(join(dir, 'src', 'smoke-scene.ts'), SMOKE_SCENE);
+    const stateAnchor = 'state: () => ({ screen: store.screen })';
+    if (!text.includes('smoke: (window as any).__FPX_SMOKE__')) {
+        if (!text.includes(stateAnchor))
+            return false;
+        text = text.replace(stateAnchor, 'state: () => ({ screen: store.screen, smoke: (window as any).__FPX_SMOKE__ })');
+    }
+    if (!text.includes('placeSmoke(scene)')) {
+        const anchor = /scene\.add\(new THREE\.HemisphereLight\([^)]*\)\);\n/;
+        if (!anchor.test(text))
+            return false;
+        text = `import { placeSmoke } from './smoke-scene';\n${text.replace(anchor, (m) => `${m}  placeSmoke(scene);\n`)}`;
+    }
+    writeFileSync(game, text);
+    return true;
+}
+async function waitJob(api, id, timeoutMs) {
+    const end = Date.now() + timeoutMs;
+    for (;;) {
+        const j = await getJob(api, id, 20);
+        if (TERMINAL.includes(j.status) || Date.now() >= end)
+            return j;
+    }
+}
+async function download(url, to) {
+    const r = await fetch(url);
+    if (!r.ok)
+        throw new Error(`${url}: HTTP ${r.status}`);
+    const b = Buffer.from(await r.arrayBuffer());
+    mkdirSync(dirname(to), { recursive: true });
+    writeFileSync(to, b);
+    return b;
+}
+export async function smokeBuild(opts, io = console) {
+    const u = ui(io, 'smoke-build');
+    const dir = resolve(opts.dir), plan = resolve(opts.plan);
+    const run = opts.run ?? realRunner;
+    const steps = [];
+    const step = (name, ok, said) => { steps.push({ step: name, ok, said }); if (!opts.json)
+        u.item(ok ? 'pass' : 'fail', `${name}: ${said}`); return ok; };
+    const finish = (verdicts) => {
+        const pass = verdicts.length === 4 && verdicts.every((v) => v.pass);
+        mkdirSync(join(dir, '.funtools'), { recursive: true });
+        writeFileSync(join(dir, SMOKE_RECORD), JSON.stringify({ at: new Date().toISOString(), pass, steps, verdicts }, null, 2) + '\n');
+        if (opts.json)
+            io.log(JSON.stringify({ pass, steps, verdicts }, null, 2));
+        else {
+            u.heading('verdicts');
+            for (const v of verdicts)
+                u.item(v.pass ? 'pass' : 'fail', `${v.name}: ${v.says}`);
+            u.summary(pass ? 'pass' : 'fail', pass ? 'the kit is ready for a full build' : 'not ready: fix what failed before a full build (the record is .funtools/smoke-build.json)');
+        }
+        return pass ? EXIT.pass : EXIT.fail;
+    };
+    const failAll = (why) => finish([
+        { name: 'model in the world', pass: false, says: why }, { name: 'locked look', pass: false, says: why },
+        { name: 'no primitives', pass: false, says: why }, { name: 'a real card', pass: false, says: why },
+    ]);
+    if (!existsSync(join(plan, 'design'))) {
+        u.error(`${plan} has no design/ folder`, '--plan <a folder with design/plan.md and design/first-look/ref-*.png>');
+        return EXIT.error;
+    }
+    const refs = (() => { try {
+        return readdirSync(join(plan, 'design', 'first-look')).filter((f) => /^ref[-_].+\.(png|jpe?g|webp)$/i.test(f)).sort();
+    }
+    catch {
+        return [];
+    } })();
+    const key = apiKey(opts.store ?? null);
+    const api = key ? apiOptions({ key, retries: 1 }) : null;
+    if (!api) {
+        u.error('not signed in: the smoke build draws through the hosted tools', '`funtools login` (or FUNPIXEL_API_KEY)');
+        return EXIT.error;
+    }
+    mkdirSync(dir, { recursive: true });
+    cpSync(join(plan, 'design'), join(dir, 'design'), { recursive: true });
+    if (!existsSync(join(dir, 'funpixel.json'))) {
+        const quiet = { log: () => { }, error: () => { } };
+        const code = await init({ target: dir, framework: 'three-world', bare: true, offline: true }, quiet);
+        if (!step('init --bare', code === 0, code === 0 ? 'three-world spine, the plan kept' : `init exited ${code}`))
+            return failAll('init failed');
+    }
+    else
+        step('init --bare', true, 'already a game folder');
+    const manifest = readJson(join(dir, 'funpixel.json')) ?? {};
+    const target = (() => { try {
+        return readdirSync(join(dir, 'design', 'first-look')).filter((f) => /^(target|look)[-_]?.*\.(png|jpe?g|webp)$/i.test(f)).sort()[0];
+    }
+    catch {
+        return undefined;
+    } })();
+    if (target && !Array.isArray(manifest.moments)) {
+        manifest.moments = [{ name: 'smoke', view: 'playing', target: `design/first-look/${target}` }];
+        writeFileSync(join(dir, 'funpixel.json'), JSON.stringify(manifest, null, 2) + '\n');
+    }
+    step('target', !!target, target ? `scored against design/first-look/${target}` : 'the plan has no target frame (design/first-look/target*.png): the look cannot be scored');
+    let gameId = manifest.game_id ?? '';
+    try {
+        if (!/^[0-9a-f]{32}$/.test(gameId)) {
+            const { json } = await sendJson(api, 'POST', '/v1/games/drafts', { body: { name: manifest.title ?? manifest.name ?? 'smoke build' } });
+            gameId = json.game_id;
+            writeFileSync(join(dir, 'funpixel.json'), JSON.stringify({ ...manifest, game_id: gameId }, null, 2) + '\n');
+        }
+    }
+    catch (e) {
+        step('game', false, `no draft id: ${e.message}`);
+        return failAll('no game id');
+    }
+    if (!refs.length)
+        step('lock', false, 'the plan has no locked sheets (design/first-look/ref-*.png): nothing to hold the look to');
+    const sheets = [];
+    for (const f of refs) {
+        try {
+            const b64 = readFileSync(join(dir, 'design', 'first-look', f)).toString('base64');
+            const { json } = await sendJson(api, 'POST', '/v1/tools/import_asset', { body: { image_base64: b64, name: f } });
+            sheets.push({ name: f.replace(/\.[^.]+$/, '').replace(/^ref_/i, 'ref-').toLowerCase(), asset_id: json.asset_id });
+        }
+        catch (e) {
+            step('lock', false, `${f} was not imported: ${e.message}`);
+        }
+    }
+    if (sheets.length)
+        step('lock', true, `${sheets.length} sheet(s) pinned: ${sheets.map((s) => s.name).join(', ')}`);
+    const style = (() => { try {
+        return readFileSync(join(dir, 'design', 'style-block.txt'), 'utf8').trim().slice(0, 1000);
+    }
+    catch {
+        return undefined;
+    } })();
+    const subject = (() => { try {
+        return readFileSync(join(dir, 'design', 'plan.md'), 'utf8').split('\n').find((l) => l.trim() && !l.startsWith('#'))?.trim().slice(0, 300);
+    }
+    catch {
+        return undefined;
+    } })() ?? 'the opening place of this game';
+    let batch;
+    try {
+        ({ json: batch } = await sendJson(api, 'POST', '/v1/tools/generate_batch', { body: {
+                game_id: gameId, batch_key: 'smoke-build', confirm_cost: true,
+                ...(sheets.length ? { lock: { ...(style ? { style } : {}), sheets } } : {}),
+                items: [{ name: IMAGE, prompt: `The world of this game, wide: ${subject}` }, { name: MODEL, kind: 'model3d', prompt: `The game's signature prop or vehicle: ${subject}` }],
+            } }));
+    }
+    catch (e) {
+        step('generate', false, `generate_batch refused: ${e.message}`);
+        return failAll('nothing was generated');
+    }
+    const item = (n) => (batch?.items ?? []).find((i) => i.name === n) ?? {};
+    const picRefs = String(item(IMAGE).references_from ?? 'none');
+    step('picture', !!item(IMAGE).job_id, `job ${item(IMAGE).job_id ?? 'not started'}, references ${picRefs}`);
+    const jobs = { [IMAGE]: null, [MODEL]: null };
+    for (const n of [IMAGE, MODEL]) {
+        const id = item(n).job_id;
+        if (!id)
+            continue;
+        try {
+            jobs[n] = await waitJob(api, id, opts.jobTimeoutMs ?? 9 * 60_000);
+        }
+        catch (e) {
+            step(n, false, e.message);
+        }
+    }
+    const land = async (n, to) => {
+        const j = jobs[n];
+        if (!j || j.status !== 'succeeded') {
+            step(n, false, j ? `${j.status}${j.error?.message ? `: ${j.error.message}` : ''} — retry it, switch provider or tier, or ask the person; never draw it in code` : 'no job');
+            return null;
+        }
+        const url = j.outputs?.[0]?.url;
+        if (!url) {
+            step(n, false, 'no file in the job');
+            return null;
+        }
+        try {
+            const b = await download(url, join(dir, to));
+            step(n, true, `${to} (${b.length} bytes)`);
+            return b;
+        }
+        catch (e) {
+            step(n, false, e.message);
+            return null;
+        }
+    };
+    const pic = await land(IMAGE, `public/assets/images/${IMAGE}.png`);
+    const glb = await land(MODEL, `public/assets/models/${MODEL}.glb`);
+    const isGlb = !!glb && glb.subarray(0, 4).toString('latin1') === 'glTF';
+    const wired = wireScene(dir);
+    step('place', wired, wired ? 'src/smoke-scene.ts loads the picture and the model; game.ts calls placeSmoke(scene)' : existsSync(join(dir, 'src', 'models.ts')) ? 'src/game.ts has no scene to place them in' : 'no src/models.ts, the spine\'s model loader: re-init with this funtools (init --bare keeps it)');
+    const out = {};
+    for (const s of ['install', 'build', 'capture', 'scene', 'world', 'score', 'card']) {
+        out[s] = await run(s, dir).catch((e) => ({ ok: false, said: e.message }));
+        step(s, out[s].ok, out[s].said || (out[s].ok ? 'done' : 'failed'));
+    }
+    const fp = (await fingerprint(dir).catch(() => null))?.fingerprint ?? null;
+    const w = worldRead(dir, fp);
+    const named = worldHolds(dir, fp).filter((h) => !/\b(NOTHING MOVES|NO HERO)\b/.test(h.line));
+    const p = readPipeline(dir);
+    const score = p ? evaluateGate(dir, { kind: 'score' }, fp, p, 'slice') : null;
+    const card = readProgress(dir).last;
+    const ok = (s) => out[s]?.ok === true, said = (s) => out[s]?.said ?? 'not run';
+    const scored = score?.state === 'met' || score?.state === 'failing';
+    const boxesFresh = w.seen.some((x) => x.check === 'boxes' && x.fresh);
+    const boxWarns = w.warns.filter((x) => x.startsWith('boxes:'));
+    const lifeNotes = w.warns.filter((x) => x.startsWith('life:'));
+    const verdicts = [
+        { name: 'model in the world', pass: isGlb && wired && ok('capture') && ok('scene'),
+            says: !isGlb ? `no generated model: ${jobs[MODEL]?.status ?? 'not started'}` : !wired ? 'the model landed but the scene was not wired'
+                : !ok('capture') ? `the model landed but the build was not captured: ${said('capture')}` : ok('scene') ? `${said('scene')}; the build captured` : `the model landed but ${said('scene')}` },
+        { name: 'locked look', pass: !!pic && picRefs.startsWith('locked') && scored,
+            says: `picture references: ${picRefs}; target score: ${score ? score.says : 'no pipeline'}${score?.state === 'failing' ? ' (recorded; the bar is the full build\'s)' : ''}` },
+        { name: 'no primitives', pass: !named.length && boxesFresh && !boxWarns.length,
+            says: named.length ? named.map((h) => h.line).slice(0, 3).join('; ') : boxWarns.length ? boxWarns.slice(0, 2).join('; ') : !boxesFresh ? `the boxes read did not run on these files (${w.says})`
+                : `the boxes read holds on the current files${lifeNotes.length ? `; for the full build: ${lifeNotes.slice(0, 2).join('; ')}` : ''}` },
+        { name: 'a real card', pass: !!card?.observed && card.shot?.source === 'capture', says: card ? `card ${card.n}: ${card.observed ? `frame ${card.shot?.path ?? card.clip?.path ?? '?'}` : `not observed (${card.why_not ?? ''})`}` : 'no card posted' },
+    ];
+    return finish(verdicts);
+}
+export const SMOKE_BUILD_HELP = `funtools smoke-build <fresh-folder> --plan <folder with design/>: init --bare, the locked sheets pinned, one picture and one 3D model through the hosted tools, placed, captured, the world read, the target scored, one card. Pass/fail on: a model in the world, the locked look, no primitives, a real card.`;

package/dist/commands/smoke.js

@@ -0,0 +1,37 @@
+import { stat } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { loadGame } from "../smoke/sources.js";
+import { art, assets, imports, placeholders } from "../smoke/checks.js";
+import { logic } from "../smoke/logic.js";
+import { palette } from "../smoke/palette.js";
+import { checkLimits } from "../pack/limits.js";
+import { ui } from "../ui.js";
+export async function smokeFindings(dir) {
+    const game = await loadGame(dir);
+    const sizes = await Promise.all(game.staged.included.map(async (path) => ({ path, size: (await stat(join(dir, path))).size })));
+    const budgets = checkLimits(sizes).map((l) => ({
+        level: l.level === 'refused' ? 'FAIL' : 'warn', check: 'asset', path: l.path, what: l.what,
+    }));
+    return [...placeholders(game), ...assets(game), ...art(game), ...palette(game), ...imports(game), ...logic(game), ...budgets];
+}
+export async function smoke(opts, io = console) {
+    const dir = resolve(opts.target ?? '.');
+    const findings = await smokeFindings(dir);
+    const failed = findings.filter((f) => f.level === 'FAIL').length;
+    if (opts.json) {
+        io.log(JSON.stringify({ failed, findings }, null, 2));
+    }
+    else {
+        const u = ui(io, 'smoke');
+        u.heading(`smoke · ${dir}`);
+        for (const f of findings) {
+            const where = f.path ? `${f.path}${f.line ? `:${f.line}` : ''}` : '';
+            u.item(f.level === 'FAIL' ? 'fail' : 'warn', where || f.what, where ? f.what : undefined);
+        }
+        if (failed)
+            u.summary('fail', `${failed} problem(s) a player will see`);
+        else
+            u.summary('pass', `clean${findings.length ? ` (${findings.length} warning(s))` : ''}`);
+    }
+    return failed ? 1 : 0;
+}

package/dist/commands/spec.js

@@ -0,0 +1,114 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { EXIT } from "./verify.js";
+import { ui } from "../ui.js";
+import { specInit } from "../spec/scaffold.js";
+import { hasSpec, lintSpec } from "../spec/lint.js";
+import { clock, specHash } from "../spec/rooms.js";
+import { SPEC_DIR } from "../spec/tunables.js";
+import { playFloor } from "../sim/judge.js";
+export const SPEC_SUBCOMMANDS = ['lint', 'init'];
+export const SPEC_RECORD = join('.funtools', 'spec.json');
+const MARK = { warn: 'warn', note: 'note', ok: 'pass', 'not measured': 'not_observed' };
+const readJson = (p) => { try {
+    return JSON.parse(readFileSync(p, 'utf8'));
+}
+catch {
+    return null;
+} };
+export function specTierOf(root) {
+    const t = readJson(join(root, 'funpixel.json'))?.production?.tier;
+    return t === 'mid' || t === 'deep' ? t : null;
+}
+export function recordLint(root, specDir = SPEC_DIR, tier = null) {
+    const r = lintSpec({ root, specDir, tier: tier ?? specTierOf(root), floor: playFloor(root) });
+    const exit = r.counts.warn ? EXIT.fail : EXIT.pass;
+    const first = r.findings.find((f) => f.state === 'warn')?.says;
+    const record = { tool: 'funtools', command: 'spec lint', exit, spec: specDir, hash: specHash(root), at: new Date().toISOString(), tier: r.tier, counts: r.counts, ...(first ? { first } : {}), tunables: r.tunables, rooms: r.rooms, par_total: r.parTotal, floor: r.floor, findings: r.findings };
+    const recPath = join(root, SPEC_RECORD);
+    mkdirSync(dirname(recPath), { recursive: true });
+    writeFileSync(recPath, JSON.stringify(record, null, 2) + '\n');
+    return { record, result: r };
+}
+function tierArg(t) {
+    if (t === undefined)
+        return null;
+    return t === 'mid' || t === 'deep' ? t : 'bad';
+}
+export async function spec(opts, io = console) {
+    const u = ui(io, `spec ${opts.sub}`);
+    const root = resolve(opts.dir ?? '.');
+    const tier = tierArg(opts.tier);
+    if (tier === 'bad') {
+        u.error(`--tier ${opts.tier}`, 'the big tier is mid or deep; a small game stays one GDD');
+        return EXIT.error;
+    }
+    if (!existsSync(root)) {
+        u.error(`no such folder: ${root}`, 'run it in the game folder');
+        return EXIT.error;
+    }
+    if (opts.sub === 'init') {
+        const r = specInit(root, { ...(tier ? { tier } : {}), now: opts.now });
+        if ('refused' in r) {
+            if (opts.json)
+                io.log(JSON.stringify({ ok: false, refused: r.refused, next: r.next }, null, 2));
+            else
+                u.summary('not_observed', `${r.refused} — ${r.next}`);
+            return EXIT.not_observed;
+        }
+        const lint = recordLint(root, SPEC_DIR, r.tier).result;
+        if (opts.json) {
+            io.log(JSON.stringify({ ok: true, ...r, lint: lint.counts }, null, 2));
+            return EXIT.pass;
+        }
+        if (r.engine === 'unity') {
+            u.heading(`spec init · the ${r.tier} tier (a Unity game: the project is ${r.unityProject})`);
+            u.item('pass', `${SPEC_DIR}/tunables.json and rooms.json: empty, in the kit's shape`, 'fill them from the GDD: every number by id, one room per place; the Unity project loads copies of them (README.md, "How Unity loads it")');
+            u.item('note', `not written, the web layer a Unity game cannot load: ${r.notWritten.join(', ')}`, 'the Unity side is an Editor step that copies the data in and an EditMode test that holds the copy to this folder');
+            u.item('note', `wrote ${r.wrote.length} files: ${r.wrote.slice(0, 12).join(', ')}${r.wrote.length > 12 ? ' …' : ''}`);
+            u.item(lint.counts.warn ? 'warn' : 'pass', `spec lint: ${lint.counts.warn ? `${lint.counts.warn} warning${lint.counts.warn === 1 ? '' : 's'} (${lint.findings.find((f) => f.state === 'warn')?.says})` : `clean (${lint.counts.note} notes)`}`, SPEC_RECORD);
+            u.heading('next');
+            u.line(`read ${SPEC_DIR}/README.md first, then fill tunables.json and rooms.json from the GDD`);
+            u.line('npx @funpixel/tools spec lint     (the folder against itself, after any edit)');
+            u.summary('pass', `the big tier's spec folder is written for a Unity game (${SPEC_DIR}/)`);
+            return EXIT.pass;
+        }
+        u.heading(`spec init · the ${r.tier} tier (${r.framework} starter)`);
+        u.item('pass', `${SPEC_DIR}/tunables.json: ${r.tunables} numbers from the code, grouped, each with where it came from`, 'give each a unit, a range and a why; src/tune.ts loads the file (tune(\'group.name\'))');
+        u.item('pass', `${SPEC_DIR}/rooms.json: ${r.rooms} rooms in two chapters of the starter's own round, pars adding up to ${clock(r.parTotal)} (floor ${clock(r.floor)})`, 'an example of content as data: replace them with the game\'s own rooms, one per place in the GDD');
+        if (r.rewired.length)
+            u.item('pass', `rewired to read tunables.json: ${r.rewired.join(', ')}`);
+        if (r.leftAlone.length)
+            u.item('warn', `left as you wrote them (numbers still typed in): ${r.leftAlone.join(', ')}`, 'spec lint names each one: read it with tune(\'id\')');
+        for (const n of r.notes)
+            u.item('note', n);
+        u.item('note', `wrote ${r.wrote.length} files: ${r.wrote.slice(0, 12).join(', ')}${r.wrote.length > 12 ? ' …' : ''}`);
+        u.item(lint.counts.warn ? 'warn' : 'pass', `spec lint: ${lint.counts.warn ? `${lint.counts.warn} warning${lint.counts.warn === 1 ? '' : 's'} (${lint.findings.find((f) => f.state === 'warn')?.says})` : `clean (${lint.counts.note} notes)`}`, SPEC_RECORD);
+        u.heading('next');
+        u.line('npx @funpixel/tools spec lint     (the folder against itself and the code, after any edit)');
+        u.line('npx @funpixel/tools rooms         (bots clear every room over 5 seeds, each against its par)');
+        u.line(`read ${SPEC_DIR}/README.md first: slice first — room 2 opens only once room 1 passes (npx @funpixel/tools rooms open <id>)`);
+        u.summary('pass', `the big tier's spec folder is written (${SPEC_DIR}/)`);
+        return EXIT.pass;
+    }
+    const specDir = opts.spec ?? SPEC_DIR;
+    if (!hasSpec(root, specDir)) {
+        if (opts.json)
+            io.log(JSON.stringify({ tool: 'funtools', command: 'spec lint', exit: EXIT.not_observed, findings: [] }, null, 2));
+        else
+            u.summary('not_observed', `no ${specDir}/ here — a small game stays one GDD; a big one: npx @funpixel/tools spec init`);
+        return EXIT.not_observed;
+    }
+    const { record, result: r } = recordLint(root, specDir, tier);
+    const exit = record.exit;
+    if (opts.json) {
+        io.log(JSON.stringify(record, null, 2));
+        return exit;
+    }
+    u.heading(`spec lint · ${specDir} · ${r.tier ?? 'no tier'} · ${r.tunables} tunables · ${r.rooms} rooms · pars ${clock(r.parTotal)} against ${clock(r.floor.seconds)}`);
+    for (const f of r.findings)
+        u.item(MARK[f.state], `${f.check}: ${f.says}`, f.next);
+    const tally = `${r.counts.warn} warn · ${r.counts.note} note · ${r.counts.ok} ok · ${r.counts['not measured']} not measured`;
+    u.summary(r.counts.warn ? 'warn' : 'pass', `${r.counts.warn ? tally : `clean (${tally})`} — ${SPEC_RECORD}`);
+    return exit;
+}

package/dist/commands/store.js

@@ -0,0 +1,154 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { EXIT } from "./verify.js";
+import { ui } from "../ui.js";
+import { ANSWERS_PATH, readAnswers, secretsIn, STORE_NAME, STORES, todos } from "../store/answers.js";
+import { starterAnswers } from "../store/init.js";
+import { storeDoctor } from "../store/doctor.js";
+import { lintAnswers } from "../store/lint.js";
+import { PLAN_STORES, storePlan } from "../store/plan.js";
+import { patchStatusStore } from "../status/status.js";
+export const STORE_SUBCOMMANDS = ['init', 'doctor', 'lint', 'plan'];
+export { STORE_PLAN_RECORD } from "../store/plan.js";
+import { STORE_PLAN_RECORD } from "../store/plan.js";
+export const NOT_BUILT = 'store push and store release are not built yet: they wait for the owner\'s decisions on production rights';
+const MARK = { pass: 'pass', warn: 'warn', fail: 'fail' };
+export function lintFile(root, a, only) {
+    const r = lintAnswers(root, a, only);
+    const found = secretsIn(readFileSync(join(root, ANSWERS_PATH), 'utf8'));
+    if (found.length) {
+        r.findings.unshift({ store: 'all', check: 'no secrets', state: 'fail', says: `${ANSWERS_PATH} holds ${found.join(', ')}`, next: 'remove it: the file is committed; name the .env variable that points at a credential instead' });
+        r.counts.fail++;
+    }
+    return r;
+}
+export async function store(opts, io = console) {
+    const u = ui(io, `store ${opts.sub}`);
+    const root = resolve(opts.dir ?? '.');
+    if (!existsSync(root)) {
+        u.error(`no such folder: ${root}`, 'run it in the game folder');
+        return EXIT.error;
+    }
+    const only = opts.store;
+    const allowed = opts.sub === 'plan' ? PLAN_STORES : STORES;
+    if (only !== undefined && !allowed.includes(only)) {
+        u.error(`--store ${only}`, `one of ${allowed.join(', ')}`);
+        return EXIT.error;
+    }
+    if (opts.sub === 'init') {
+        if (existsSync(join(root, ANSWERS_PATH))) {
+            if (opts.json)
+                io.log(JSON.stringify({ ok: false, refused: `${ANSWERS_PATH} is already there` }, null, 2));
+            else
+                u.summary('not_observed', `${ANSWERS_PATH} is already there — edit it; store lint says what is left`);
+            return EXIT.not_observed;
+        }
+        const a = starterAnswers(root, only ? [only] : ['play', 'ios']);
+        const p = join(root, ANSWERS_PATH);
+        mkdirSync(dirname(p), { recursive: true });
+        writeFileSync(p, JSON.stringify(a, null, 2) + '\n');
+        const left = todos(a);
+        if (opts.json) {
+            io.log(JSON.stringify({ ok: true, wrote: ANSWERS_PATH, from: a.sources, todos: left }, null, 2));
+            return EXIT.pass;
+        }
+        u.heading(`store init · ${ANSWERS_PATH}`);
+        for (const [k, v] of Object.entries(a.sources ?? {}))
+            u.item('pass', `${k}: ${v}`);
+        u.item('note', `${left.length} answers left as TODO — none guessed`, 'ids, prices, the SDK list, ages and categories are the owner\'s');
+        u.heading('next');
+        u.line('fill the TODOs in store/answers.json (no secret goes in it: a key is named by its .env variable)');
+        u.line('npx @funpixel/tools store lint     (the answers against each store\'s rules)');
+        u.line('npx @funpixel/tools store doctor   (what this Mac has set up for each store)');
+        u.summary('pass', `wrote ${ANSWERS_PATH}`);
+        return EXIT.pass;
+    }
+    const read = readAnswers(root);
+    const answers = 'answers' in read ? read.answers : null;
+    if (opts.sub === 'doctor') {
+        const stores = only ? [only] : [...STORES];
+        const lines = storeDoctor({ root, answers, stores, env: opts.env, run: opts.run, platform: opts.platform });
+        if (!answers)
+            lines.unshift({ store: stores[0], check: 'answers file', state: 'warn', says: 'error' in read ? read.error : '', next: 'npx @funpixel/tools store init' });
+        const failed = lines.some((l) => l.state === 'fail');
+        const exit = failed ? EXIT.fail : EXIT.pass;
+        if (opts.json) {
+            io.log(JSON.stringify({ tool: 'funtools', command: 'store doctor', exit, network: false, lines }, null, 2));
+            return exit;
+        }
+        printByStore(u, lines, stores, (l) => [MARK[l.state], `${l.check}: ${l.says}`, l.next]);
+        u.line(NOT_BUILT, 0);
+        u.summary(failed ? 'fail' : 'pass', failed ? `${lines.filter((l) => l.state === 'fail').length} to set up (each line says how)` : 'nothing missing that this Mac can see');
+        return exit;
+    }
+    if (!answers) {
+        const says = 'error' in read ? read.error : '';
+        if (opts.json)
+            io.log(JSON.stringify({ tool: 'funtools', command: `store ${opts.sub}`, exit: EXIT.not_observed, error: says }, null, 2));
+        else
+            u.summary('not_observed', `${says} — npx @funpixel/tools store init writes a starter`);
+        return /not JSON|not a JSON/.test(says) ? EXIT.error : EXIT.not_observed;
+    }
+    if (opts.sub === 'lint') {
+        const r = lintFile(root, answers, only);
+        const exit = r.counts.fail ? EXIT.fail : EXIT.pass;
+        if (opts.json) {
+            io.log(JSON.stringify({ tool: 'funtools', command: 'store lint', exit, ...r }, null, 2));
+            return exit;
+        }
+        printByStore(u, r.findings, ['all', ...r.stores], (f) => [MARK[f.state], `${f.check}: ${f.says}`, f.next]);
+        u.summary(r.counts.fail ? 'fail' : r.counts.warn ? 'warn' : 'pass', `${r.counts.fail} fail · ${r.counts.warn} warn · ${r.counts.pass} pass (${r.stores.map((s) => STORE_NAME[s]).join(', ')})`);
+        return exit;
+    }
+    const stores = (only ? [only] : PLAN_STORES.filter((s) => answers[s]));
+    if (!stores.length) {
+        u.summary('not_observed', `${ANSWERS_PATH} has no play or ios section`);
+        return EXIT.not_observed;
+    }
+    const lint = lintFile(root, answers);
+    const doctor = storeDoctor({ root, answers, stores, env: opts.env, run: opts.run, platform: opts.platform });
+    const plans = stores.map((s) => storePlan(root, answers, s, lint, doctor));
+    const record = {
+        tool: 'funtools', command: 'store plan', at: new Date().toISOString(), network: false, push: NOT_BUILT,
+        lint: lint.counts,
+        stores: Object.fromEntries(plans.map((p) => [p.store, { hash: p.hash, next: p.next ? `${p.next.n}. ${p.next.row}` : null, steps: p.steps }])),
+    };
+    const out = join(root, STORE_PLAN_RECORD);
+    mkdirSync(dirname(out), { recursive: true });
+    writeFileSync(out, JSON.stringify(record, null, 2) + '\n');
+    patchStatusStore(root);
+    if (opts.json) {
+        io.log(JSON.stringify(record, null, 2));
+        return EXIT.pass;
+    }
+    const STATE = { done: 'pass', ready: 'note', 'needs-answer': 'todo', 'needs-setup': 'todo', 'needs-build': 'todo', 'not-needed': 'skip' };
+    for (const p of plans) {
+        u.heading(`${STORE_NAME[p.store]} · plan ${p.hash.slice(0, 12)}`);
+        for (const s of p.steps) {
+            u.item(STATE[s.state], `${s.n}. [${s.who}] ${s.row} — ${s.state}`, s.how);
+            for (const t of s.true)
+                u.line(`true: ${t}`, 3);
+            for (const n of s.needs.slice(0, 4))
+                u.line(`needs: ${n}`, 3);
+            if (s.needs.length > 4)
+                u.line(`… ${s.needs.length - 4} more (--json)`, 3);
+        }
+        if (p.next)
+            u.line(`next: ${p.next.n}. ${p.next.row} [${p.next.who}]`, 1);
+    }
+    u.line(NOT_BUILT, 0);
+    u.summary('pass', `${STORE_PLAN_RECORD} (${plans.map((p) => `${p.store} ${p.hash.slice(0, 12)}`).join(', ')})`);
+    return EXIT.pass;
+}
+function printByStore(u, rows, order, fmt) {
+    for (const s of order) {
+        const mine = rows.filter((r) => r.store === s);
+        if (!mine.length)
+            continue;
+        u.heading(s === 'all' ? 'every store' : STORE_NAME[s]);
+        for (const r of mine) {
+            const [m, t, n] = fmt(r);
+            u.item(m, t, m === 'pass' ? undefined : n);
+        }
+    }
+}