@funpixel/tools 0.0.0-stage → 0.1.1

package/dist/commands/gen.js

@@ -0,0 +1,512 @@
+import { randomUUID } from 'node:crypto';
+import { apiOptions, ApiError, sendJson } from "../api/http.js";
+import { estimate, followJob, submit } from "../api/jobs.js";
+import { existsSync, readFileSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { basename, dirname, extname, join, resolve as resolvePath } from 'node:path';
+import { genNotes, genRequest, isAssetId, localModelOf } from "../gen/kinds.js";
+import { modelsOf } from "../gen/models.js";
+import { providerFor } from "../gen/local/index.js";
+import { generatedBy, LocalFailure, LocalRefusal, realMachine } from "../gen/local/provider.js";
+import { assetOf, recordAssets } from "../gen/record.js";
+import { titleGuard } from "../gen/title.js";
+import { saveLocal, saveOutputs, servedAs } from "../gen/save.js";
+import { afterSave, looksLikeUnity, unityOut, unityProject } from "../gen/unity.js";
+import { snapGenerated } from "./assets-pixels.js";
+import { kb } from "../pack/limits.js";
+import { laneOf, laneSpend, laneSpendRefusal } from "../lanes/where.js";
+import { askYes, ui } from "../ui.js";
+import { decodePng } from "../look/png.js";
+import { keepLine, readCast } from "../cast/library.js";
+import { fixPrompt, identityFacts } from "../cast/measure.js";
+import { references, scoreSaved } from "../fidelity/run.js";
+export const GEN_EXIT = { done: 0, failed: 1, refused: 2, error: 3 };
+const REFUSALS = new Set(['unknown_model', 'model_needs_plan', 'model_runs_locally', 'model_unavailable', 'confirmation_required', 'insufficient_credits', 'key_budget_exceeded', 'paid_plan_required', 'content_refused', 'rate_limited', 'too_many_jobs', 'too_many_streams', 'unauthorized', 'insufficient_scope']);
+const secs = (ms) => `${ms < 10_000 ? (ms / 1000).toFixed(1) : Math.round(ms / 1000)}s`;
+const num = (b, k) => (typeof b[k] === 'number' ? b[k] : 0);
+function modelList(b) {
+    const models = Array.isArray(b.models) ? b.models : [];
+    const ids = models.filter((m) => typeof m.id === 'string').map((m) => (m.recommended ? `${m.id} (recommended)` : String(m.id)));
+    return ids.length ? ids.join(' | ') : '<id>';
+}
+export function explain(e) {
+    const b = e.body;
+    switch (e.code) {
+        case 'confirmation_required':
+            return [`this costs about ${num(b, 'estimate_credits')} credits, above the ${num(b, 'confirm_threshold_credits')}-credit confirm line`, 'rerun with --yes to run it'];
+        case 'insufficient_credits':
+            return [`not enough credits: it needs about ${num(b, 'estimate_credits')}, ${num(b, 'available_credits')} are free`, 'top up, wait for running jobs to settle, or ask for less (--quality low)'];
+        case 'key_budget_exceeded':
+            return [`this key's monthly cap is ${num(b, 'cap_credits')} credits and ${num(b, 'used_credits')} are used`, 'raise the cap in Settings › Developers, or use another key'];
+        case 'paid_plan_required': return ['the Tools API needs a paid plan', 'upgrade in Settings › Billing'];
+        case 'rate_limited': return ['rate limited, still after waiting', 'wait a minute and run it again'];
+        case 'too_many_jobs': return ['too many of your jobs are running', 'wait for one to finish (funtools job <id> --wait)'];
+        case 'too_many_streams': return ['too many event streams are open for your account', 'close another funtools gen, or use --no-wait'];
+        case 'invalid_input': return [`the server refused the input: ${e.message}`, 'fix the option it names'];
+        case 'unknown_model': return [`not a model here: ${e.message}`, `give --model ${modelList(b)}, or drop --model for our pick`];
+        case 'model_needs_plan': return [`${typeof b.reason === 'string' ? b.reason : 'this model is on paid plans'}`, 'upgrade in Settings › Billing, or drop --model'];
+        case 'model_runs_locally': return ['that model runs on your machine, not on the server', `run: ${typeof b.run === 'string' ? b.run : 'funtools gen … --model <id>'}`];
+        case 'model_unavailable': return [`${typeof b.reason === 'string' ? b.reason : 'that model is switched off on the server'}`, `drop --model for our pick, or give --model ${modelList(b)}`];
+        case 'content_refused': return ['the content screen refused this prompt; nothing was charged', 'describe the asset in other words'];
+        case 'screen_unavailable': return ['the content screen could not answer; nothing was started', 'run it again in a moment'];
+        case 'tool_unavailable': return ['this tool is switched off on the server', 'try again later'];
+        case 'not_found': return [`no such job, or not yours: ${e.message}`, 'check the id (funtools gen prints it)'];
+        case 'network': return [e.message, 'check the connection and FUNPIXEL_API_URL'];
+        case 'no_key': return ['no API key', 'run `funtools login --key fp_live_…` or set FUNPIXEL_API_KEY (Settings › Developers, paid plans)'];
+    }
+    if (e.status === 401)
+        return ['the API key was refused', 'store a current one: funtools login --key fp_live_…'];
+    if (e.status === 403)
+        return [e.message, 'use a key with the tools:run and jobs:read scopes (Settings › Developers)'];
+    return [`${e.message} (${e.code})`, 'run it again; if it repeats, report the job id'];
+}
+const splitNext = (m) => {
+    const i = m.indexOf(' — ');
+    return i < 0 ? [m, 'run it again; if it repeats, report the command you ran'] : [m.slice(0, i), m.slice(i + 3)];
+};
+export function fail(r, e, jobId) {
+    const api = e instanceof ApiError ? e : null;
+    const [what, next] = api ? explain(api) : splitNext(e instanceof Error ? e.message : String(e));
+    if (r.json)
+        r.io.log(JSON.stringify({ ok: false, ...(jobId ? { job_id: jobId } : {}), error: { code: api?.code ?? 'error', status: api?.status ?? 0, message: what, next, ...(api?.body ?? {}) } }, null, 2));
+    r.u.error(what, next);
+    return api && REFUSALS.has(api.code) ? GEN_EXIT.refused : GEN_EXIT.error;
+}
+export function needKey(r, make = apiOptions) {
+    const api = make();
+    if (!api)
+        fail(r, new ApiError(401, 'no_key', 'no API key'), undefined);
+    return api;
+}
+function castFacts(game, c, saved) {
+    let master;
+    try {
+        master = decodePng(readFileSync(join(game, c.master)));
+    }
+    catch {
+        return [];
+    }
+    return saved.filter((s) => /\.png$/i.test(s.path)).flatMap((s) => {
+        try {
+            return [{ path: s.path, facts: identityFacts(master, decodePng(readFileSync(s.path)), c.mode) }];
+        }
+        catch {
+            return [];
+        }
+    });
+}
+export async function finish(r, api, jobId, kind, prompt, out, game = process.cwd(), check, unity, score) {
+    const progress = r.json ? null : r.u.progress();
+    const started = Date.now();
+    let phase = 'queued';
+    const show = () => progress?.update(`job ${jobId.slice(0, 8)} · ${phase}${r.u.caps.tty ? ` · ${Math.round((Date.now() - started) / 1000)}s` : ''}`);
+    const tick = r.u.caps.tty && progress ? setInterval(show, 1000) : undefined;
+    show();
+    let job;
+    try {
+        job = await followJob({ ...api, onWait: (why, ms) => { phase = `${why} (${secs(ms)})`; show(); } }, jobId, (ev) => {
+            phase = ev.name === 'started' ? 'running' : ev.name === 'asset' ? `made ${String(ev.data.data?.name ?? 'a file')}` : ev.name;
+            show();
+        });
+    }
+    catch (e) {
+        return fail(r, e, jobId);
+    }
+    finally {
+        clearInterval(tick);
+    }
+    if (job.status !== 'succeeded') {
+        const why = job.error ? `${job.error.message} (${job.error.code})` : job.status;
+        progress?.done('fail', `job ${jobId} ${job.status}`);
+        if (r.json)
+            r.io.log(JSON.stringify({ ok: false, job_id: jobId, status: job.status, error: job.error, charged_credits: job.charged_credits }, null, 2));
+        r.u.error(`the job ${job.status}: ${why}`, job.status === 'cancelled' ? 'run gen again to make a new one' : 'change the prompt or options and run it again; a failed job is not charged');
+        return GEN_EXIT.failed;
+    }
+    let saved;
+    try {
+        saved = await saveOutputs(job, kind, prompt, game, out);
+    }
+    catch (e) {
+        return fail(r, e, jobId);
+    }
+    const scored = score ? await scoreSaved(game, saved, score) : undefined;
+    let unityNotes = [];
+    if (unity) {
+        try {
+            ({ files: saved, notes: unityNotes } = afterSave(unity, kind, saved));
+        }
+        catch (e) {
+            return fail(r, e, jobId);
+        }
+    }
+    const pixel = snapGenerated(game, kind, saved.map((s) => s.path));
+    const identity = check ? castFacts(game, check, saved) : [];
+    if (r.json)
+        laneSpend(game, { kind, tool: job.tool, credits: job.charged_credits ?? 0, job_id: job.job_id });
+    if (r.json) {
+        r.io.log(JSON.stringify({
+            ok: true, job_id: job.job_id, tool: job.tool, status: job.status,
+            estimate_credits: job.estimate_credits, charged_credits: job.charged_credits,
+            files: saved.map((s) => ({ ...s, served_as: servedAs(game, s.path) })), result: job.result,
+            ...(pixel.note ? { pixel_art: pixel } : {}),
+            ...(check ? { identity: { cast: check.id, master: check.master, results: identity } } : {}),
+            ...(scored ? { fidelity: scored } : {}),
+            ...(unity ? { unity: { project: unity, notes: unityNotes } } : {}),
+        }, null, 2));
+        return GEN_EXIT.done;
+    }
+    progress?.done('pass', `job ${jobId} succeeded`);
+    laneSpend(game, { kind, tool: job.tool, credits: job.charged_credits ?? 0, job_id: job.job_id });
+    for (const s of saved)
+        r.u.item('pass', servedAs(game, s.path), `${kb(s.bytes)}, ${s.content_type}`);
+    for (const n of unityNotes)
+        r.u.item(/kept as|no glTFast|not the kit/.test(n) ? 'warn' : 'note', n);
+    if (pixel.note)
+        r.u.item('note', pixel.note);
+    for (const x of identity) {
+        const f = x.facts;
+        r.u.item(f.verdict === 'drift' ? 'warn' : f.verdict === 'not_observed' ? 'note' : 'pass', `identity vs ${check.id}'s master: ${f.verdict}`, f.iou === null ? f.why.join('; ') : `silhouette ${Math.round(f.iou * 100)}% · colour ${f.palette}%${f.why.length ? ` · ${f.why.join('; ')}` : ''}${f.verdict === 'drift' ? ` — fix it once: funtools gen edit "${fixPrompt(f, undefined).replace(/"/g, "'")}" --asset ${servedAs(game, x.path).replace(/^\//, 'public/')} ; or make it through \`assets gen\` (edit, then redraw, automatically)` : ''}`);
+    }
+    if (scored && 'error' in scored)
+        r.u.item('warn', `not scored: ${scored.error}`, `score it later: funtools fidelity <model> ${score.map((x) => `${x.name}=${x.path}`).join(' ')}`);
+    else if (scored) {
+        for (const [name, v] of Object.entries(scored.views))
+            r.u.item(v ? 'note' : 'not_observed', v ? `fidelity ${name} ${v.total}% (silhouette ${v.silhouette} · palette ${v.palette} · structure ${v.structure} · lines ${v.lines})` : `fidelity ${name}: no shape found in the picture`);
+        for (const f of scored.consistency.findings)
+            r.u.item('warn', `references disagree (${f.check}): ${f.says}`);
+        if (scored.mean !== null)
+            r.u.line(`fidelity mean ${scored.mean}% — scores.json and sheets in ${scored.out}`, 2);
+    }
+    const summary = job.result?.summary;
+    if (typeof summary === 'string')
+        for (const l of summary.split('\n').filter(Boolean))
+            r.u.line(l, 2);
+    r.u.summary('pass', `done — charged ${job.charged_credits} credit(s)${job.waived_credits ? `, ${job.waived_credits} waived` : ''}`);
+    return GEN_EXIT.done;
+}
+const confirm = (r, e) => !r.json && askYes(r.io, r.u, `about ${num(e.body, 'estimate_credits')} credits — run it?`);
+async function genLocal(r, req, model, opts) {
+    const provider = providerFor(model.id);
+    if (!provider)
+        return fail(r, new Error(`${model.id} has no runner in this funtools yet — drop --model for our pick`));
+    if (opts.unity !== undefined)
+        return fail(r, new Error(`--unity takes hosted files only for now — drop --unity (then copy the file in), or drop --model for our pick`));
+    if (!opts.wait)
+        return fail(r, new Error(`${model.id} runs on this machine and now, so there is no job to wait for — drop --no-wait`));
+    const m = opts.machine ?? realMachine();
+    const game = opts.dir ?? process.cwd();
+    const check = provider.check(m);
+    if (check.state !== 'installed') {
+        const what = check.says;
+        if (r.json)
+            r.io.log(JSON.stringify({ ok: false, model: model.id, where: 'local', error: { code: check.state === 'missing' ? 'local_model_missing' : 'local_model_unsupported', message: what, ...(check.state === 'missing' ? { fix: check.fix } : {}) } }, null, 2));
+        r.u.error(what);
+        return GEN_EXIT.refused;
+    }
+    const input = { ...req.input };
+    if (typeof input.voice_asset_id === 'string' && !isAssetId(input.voice_asset_id))
+        input.voice_asset_id = resolvePath(game, input.voice_asset_id);
+    if (!r.json)
+        r.u.heading(`gen ${req.kind} · ${model.id} on this Mac (free, not checked by us)${req.prompt ? ` · ${req.prompt}` : ''}`);
+    const progress = r.json ? null : r.u.progress();
+    let made;
+    try {
+        made = await provider.run({ tool: req.tool, input }, game, m, (line) => progress?.update(`${model.id} · ${line.slice(0, 100)}`));
+    }
+    catch (e) {
+        progress?.done('fail', `${model.id} did not run`);
+        if (e instanceof LocalRefusal) {
+            if (r.json)
+                r.io.log(JSON.stringify({ ok: false, model: model.id, where: 'local', error: { code: 'refused', message: e.message } }, null, 2));
+            r.u.error(e.message);
+            return GEN_EXIT.refused;
+        }
+        if (e instanceof LocalFailure) {
+            if (r.json)
+                r.io.log(JSON.stringify({ ok: false, model: model.id, where: 'local', error: { code: 'local_run_failed', message: e.message } }, null, 2));
+            r.u.error(e.message);
+            return GEN_EXIT.failed;
+        }
+        return fail(r, e);
+    }
+    progress?.done('pass', `${model.id} spoke it`);
+    let saved;
+    try {
+        saved = await saveLocal(made.files, req.kind, req.prompt || opts.name || '', game, req.tool, generatedBy(model.id), opts.out);
+    }
+    catch (e) {
+        return fail(r, e);
+    }
+    if (r.json) {
+        r.io.log(JSON.stringify({ ok: true, model: model.id, where: 'local', generated_by: generatedBy(model.id), tool: req.tool, charged_credits: 0, files: saved.map((s) => ({ ...s, served_as: servedAs(game, s.path) })), result: made.result }, null, 2));
+        return GEN_EXIT.done;
+    }
+    for (const s of saved)
+        r.u.item('pass', servedAs(game, s.path), `${kb(s.bytes)}, ${s.content_type}`);
+    const summary = made.result.summary;
+    if (typeof summary === 'string')
+        r.u.line(summary, 2);
+    const ours = modelsOf(model.kind).find((x) => x.recommended);
+    r.u.summary('pass', `done — free, made on this Mac by ${model.id} (recorded as ${generatedBy(model.id)})${ours ? `; ours, ${ours.id}, stays the recommended pick` : ''}`);
+    return GEN_EXIT.done;
+}
+const IMAGE = /\.(png|jpe?g|webp|gif)$/i;
+async function assetIdOf(given, flag, api, note) {
+    if (typeof given !== 'string' || isAssetId(given) || !existsSync(given))
+        return given;
+    const path = given;
+    let found = await assetOf(path);
+    if ('why' in found && api && IMAGE.test(path)) {
+        const bytes = await readFile(path);
+        const { json } = await sendJson(api, 'POST', '/v1/tools/import_asset', { body: { image_base64: bytes.toString('base64'), name: basename(path) } });
+        await recordAssets(gameRoot(path), json.job_id, 'import_asset', [{ path, asset_id: json.asset_id, bytes }]);
+        note?.(`imported ${basename(path)} as asset ${json.asset_id} (free): ${found.why}`);
+        found = { asset_id: json.asset_id };
+    }
+    if ('why' in found)
+        throw new Error(`${flag} ${path}: ${found.why} — pass the asset id a job printed, or make the file with gen first`);
+    return found.asset_id;
+}
+export async function resolveAsset(req, api, note) {
+    const files = (v) => typeof v === 'string' && !isAssetId(v) && existsSync(v);
+    const refs = Array.isArray(req.input.references) ? req.input.references : [];
+    const pictures = ['end_image_asset_id', 'reference_image_asset_id', 'video_asset_id', 'audio_asset_id'];
+    const views = (req.input.view_asset_ids ?? {});
+    if (req.kind === 'dialogue')
+        return { ...req, input: await sceneVoices(req.input, note) };
+    if (!files(req.input.asset_id) && !files(req.input.voice_asset_id) && !files(req.input.image_asset_id) && !refs.some(files) && !pictures.some((k) => files(req.input[k])) && !Object.values(views).some(files))
+        return req;
+    const input = { ...req.input };
+    if (files(input.image_asset_id))
+        input.image_asset_id = await assetIdOf(input.image_asset_id, '--image-asset', api, note);
+    if (Object.values(views).some(files)) {
+        const resolved = {};
+        for (const [side, v] of Object.entries(views))
+            resolved[side] = files(v) ? await assetIdOf(v, `--${side}-asset`, api, note) : v;
+        input.view_asset_ids = resolved;
+    }
+    if (Array.isArray(input.references))
+        input.references = await Promise.all(input.references.map((r) => assetIdOf(r, '--references', api, note)));
+    for (const k of pictures)
+        if (files(input[k]))
+            input[k] = await assetIdOf(input[k], `--${k.replace(/_id$/, '').replace(/_/g, '-')}`, api, note);
+    if (input.voice_asset_id !== undefined)
+        input.voice_asset_id = await assetIdOf(input.voice_asset_id, '--voice', undefined, note);
+    const given = input.asset_id;
+    if (typeof given !== 'string' || isAssetId(given) || !existsSync(given))
+        return { ...req, input };
+    input.asset_id = await assetIdOf(given, '--asset', api, note);
+    const stem = basename(given, extname(given));
+    return { ...req, input, prompt: [stem, req.kind === 'sheet' ? 'sheet' : req.prompt].filter(Boolean).join(' ') };
+}
+async function sceneVoices(input, note) {
+    const out = { ...input };
+    if (Array.isArray(out.lines)) {
+        out.lines = await Promise.all(out.lines.map(async (l, i) => l && typeof l === 'object' && 'voice' in l ? { ...l, voice: await assetIdOf(l.voice, `lines[${i}].voice`, undefined, note) } : l));
+    }
+    if (out.cast && typeof out.cast === 'object' && !Array.isArray(out.cast)) {
+        const cast = {};
+        for (const [k, v] of Object.entries(out.cast))
+            cast[k] = await assetIdOf(v, `cast.${k}`, undefined, note);
+        out.cast = cast;
+    }
+    return out;
+}
+function gameRoot(path) {
+    for (let d = dirname(resolvePath(path));; d = dirname(d)) {
+        if (existsSync(join(d, 'funpixel.json')) || existsSync(join(d, 'package.json')))
+            return d;
+        if (dirname(d) === d)
+            return dirname(resolvePath(path));
+    }
+}
+export function castFlags(positionals, flags, game) {
+    const id = flags['--cast'];
+    if (id === undefined)
+        return { positionals, flags };
+    const { ['--cast']: _drop, ...rest } = flags;
+    const m = typeof id === 'string' ? readCast(game).get(id) : undefined;
+    if (!m)
+        throw new Error(`--cast ${String(id)} is not in design/cast/ — funtools cast list names them; accept one with funtools cast add`);
+    const [kind, ...words] = positionals;
+    const abs = (p) => join(game, p);
+    const out = { ...rest };
+    const keep = keepLine(m);
+    let pos = positionals;
+    if (['image', 'sprite', 'texture', 'strip'].includes(kind)) {
+        const given = typeof out['--references'] === 'string' ? String(out['--references']).split(',').map((s) => s.trim()).filter(Boolean) : [];
+        out['--references'] = [...new Set([abs(m.master), ...(m.turnaround ? [abs(m.turnaround)] : []), ...given])].slice(0, 16).join(',');
+        pos = [kind, [...words, keep].join(' ')];
+    }
+    else if (kind === 'edit' || kind === 'sheet') {
+        if (out['--asset'] === undefined)
+            out['--asset'] = abs(m.master);
+        if (kind === 'edit')
+            pos = [kind, [...words, keep].join(' ')];
+    }
+    else if (kind === 'model3d') {
+        if (out['--image-asset'] === undefined && out['--image-url'] === undefined)
+            out['--image-asset'] = abs(m.master);
+    }
+    else
+        throw new Error(`--cast is for image, sprite, texture, strip, edit, sheet and model3d, not ${kind}`);
+    const mode = kind === 'edit' && out['--mode'] !== 'pose' ? 'same' : 'pose';
+    return { positionals: pos, flags: out, ...(['model3d', 'sheet'].includes(kind) ? {} : { check: { id: m.card.id, master: m.master, mode } }) };
+}
+export async function gen(opts, io = console) {
+    const r = { u: ui(io, 'gen'), json: opts.json, io };
+    let req;
+    let check;
+    try {
+        const c = castFlags(opts.positionals, opts.flags, opts.dir ?? process.cwd());
+        check = c.check;
+        req = genRequest(c.positionals, c.flags);
+    }
+    catch (e) {
+        return fail(r, e);
+    }
+    const local = localModelOf(req);
+    if (local)
+        return genLocal(r, req, local, opts);
+    let score;
+    if (opts.score !== undefined) {
+        const refs = req.kind === 'model3d' ? references(opts.score.split(',').map((x) => x.trim()).filter(Boolean)) : '--score is for model3d';
+        if (typeof refs === 'string')
+            return fail(r, new Error(`--score: ${refs} — e.g. --score profile=refs/side.png,end=refs/end.png`));
+        if (!opts.wait)
+            return fail(r, new Error('--score scores the model when it lands, so it waits — drop --no-wait, or run funtools fidelity after `funtools job <id> --wait`'));
+        score = refs;
+    }
+    let unity;
+    let out = opts.out;
+    if (opts.unity !== undefined) {
+        const found = unityProject(opts.unity);
+        if ('why' in found)
+            return fail(r, new Error(`${found.why} — name the folder that holds Assets/ and ProjectSettings/`));
+        if (opts.out !== undefined)
+            return fail(r, new Error('--unity picks the folder itself — drop --out, or drop --unity and name the file'));
+        if (!opts.wait)
+            return fail(r, new Error('--unity readies the files for Unity as the job lands — drop --no-wait'));
+        const to = unityOut(found.project, req.kind, req.prompt, req.input.loop === true);
+        if ('why' in to)
+            return fail(r, new Error(to.why));
+        unity = found.project;
+        out = to.dir;
+        opts = { ...opts, dir: found.project };
+        if (req.kind === 'model3d' && req.input.raw !== true)
+            req = { ...req, input: { ...req.input, raw: true } };
+    }
+    else if (!r.json && looksLikeUnity(opts.dir ?? process.cwd())) {
+        r.u.item('warn', 'this folder is a Unity project: --unity . writes into Assets/_Game/Generated/ with import settings, where public/assets/ is for a web game');
+    }
+    if (!r.json)
+        for (const n of genNotes(req))
+            r.u.item('warn', n);
+    try {
+        const t = titleGuard(req, opts.dir ?? process.cwd(), !!opts.stripTitle);
+        req = t.req;
+        if (t.note && !r.json)
+            r.u.item(opts.stripTitle ? 'note' : 'warn', t.note);
+    }
+    catch (e) {
+        return fail(r, e);
+    }
+    const api = needKey(r, opts.api);
+    if (!api)
+        return GEN_EXIT.error;
+    try {
+        req = await resolveAsset(req, api, (l) => !r.json && r.u.item('note', l));
+    }
+    catch (e) {
+        return fail(r, e);
+    }
+    const where = opts.dir ?? process.cwd();
+    if (laneOf(where)) {
+        let quoted;
+        try {
+            quoted = Number((await estimate(api, req.tool, req.input)).estimate_credits) || 0;
+        }
+        catch (e) {
+            r.u.error(`a paid call in a lane's checkout is priced against its cap first, and the estimate failed: ${e.message}`, 'try again; the cap is never skipped');
+            return GEN_EXIT.refused;
+        }
+        const capped = laneSpendRefusal(where, quoted, `gen ${req.kind} (about ${quoted} credits)`);
+        if (capped) {
+            if (r.json)
+                io.log(JSON.stringify({ ok: false, code: 'lane_cap', estimate_credits: quoted, why: capped }, null, 2));
+            r.u.error(capped);
+            return GEN_EXIT.refused;
+        }
+    }
+    if (!r.json)
+        r.u.heading(`gen ${req.kind}${req.prompt ? ` · ${req.prompt}` : ''}`);
+    const idempotencyKey = randomUUID();
+    const waits = { ...api, onWait: (why, ms) => !r.json && r.u.item('note', `${why} — retrying in ${secs(ms)}`) };
+    let submitted;
+    try {
+        submitted = await submit(waits, req.tool, req.input, { idempotencyKey, confirm: opts.yes });
+    }
+    catch (e) {
+        if (!(e instanceof ApiError) || e.code !== 'confirmation_required' || !(await confirm(r, e)))
+            return fail(r, e);
+        try {
+            submitted = await submit(waits, req.tool, req.input, { idempotencyKey, confirm: true });
+        }
+        catch (e2) {
+            return fail(r, e2);
+        }
+    }
+    const { job } = submitted;
+    if (!opts.wait) {
+        if (r.json)
+            io.log(JSON.stringify({ ok: true, job_id: job.job_id, status: job.status, estimate_credits: job.estimate_credits }, null, 2));
+        else
+            r.u.summary('pass', `queued job ${job.job_id} (about ${job.estimate_credits} credits) — \`funtools job ${job.job_id} --wait\` saves its files`);
+        return GEN_EXIT.done;
+    }
+    if (!r.json)
+        r.u.item('note', `job ${job.job_id}${submitted.replay ? ' (the one an earlier try made)' : ''} · about ${job.estimate_credits} credit(s)`);
+    return finish(r, api, job.job_id, req.kind, req.prompt || opts.name || '', out, opts.dir, check, unity, score);
+}
+export async function estimateCommand(opts, io = console) {
+    const r = { u: ui(io, 'estimate'), json: opts.json, io };
+    let req;
+    try {
+        req = genRequest(opts.positionals, opts.flags);
+    }
+    catch (e) {
+        return fail(r, e);
+    }
+    const local = localModelOf(req);
+    if (local) {
+        if (r.json)
+            io.log(JSON.stringify({ ok: true, model: local.id, where: 'local', estimate_credits: 0, requires_confirmation: false }, null, 2));
+        else
+            r.u.summary('pass', `${req.kind}: free — ${local.id} runs on this Mac (not checked by us; our pick stays recommended)`);
+        return GEN_EXIT.done;
+    }
+    const api = needKey(r);
+    if (!api)
+        return GEN_EXIT.error;
+    try {
+        req = await resolveAsset(req, api, (l) => !r.json && r.u.item('note', l));
+    }
+    catch (e) {
+        return fail(r, e);
+    }
+    try {
+        const q = await estimate(api, req.tool, req.input);
+        if (r.json)
+            io.log(JSON.stringify({ ok: true, ...q }, null, 2));
+        else {
+            r.u.summary('pass', `${req.kind}: about ${q.estimate_credits} credit(s)`);
+            if (q.requires_confirmation)
+                r.u.item('warn', `above the ${q.confirm_threshold_credits}-credit confirm line — gen asks first, or takes --yes`);
+        }
+        return GEN_EXIT.done;
+    }
+    catch (e) {
+        return fail(r, e);
+    }
+}

package/dist/commands/greenlight.js

@@ -0,0 +1,148 @@
+import { existsSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { EXIT } from "./verify.js";
+import { drift, lockDesign, readLock } from "../greenlight/lock.js";
+import { writePage } from "../greenlight/page.js";
+import { ui } from "../ui.js";
+import { lockRefusal } from "../studio/forks.js";
+import { studioFor } from "./pitch.js";
+import { needsOwner, worthGate, WORTH_FILE, WORTH_TITLE } from "../gdd/worth.js";
+import { chooseWorth, ensurePrototype, optionWords, recordWorth, setTarget } from "../greenlight/worth.js";
+export const GREENLIGHT_SUBCOMMANDS = ['lock', 'page', 'worth'];
+export async function greenlight(opts, io = console) {
+    const u = ui(io, 'greenlight');
+    const root = resolve(opts.dir);
+    if (!existsSync(join(root, 'design')) && opts.sub !== 'status') {
+        u.error(`no design/ folder in ${root}`, 'run it in the game folder, after the GDD\'s v0.1');
+        return EXIT.error;
+    }
+    try {
+        if (opts.sub === 'worth')
+            return worth(root, opts, u, io);
+        if (opts.sub === 'lock') {
+            if (!opts.version) {
+                u.error('lock needs --version', 'funtools greenlight lock --version v1.0');
+                return EXIT.error;
+            }
+            const held = (existsSync(join(root, 'design', 'studio.json')) ? lockRefusal(root, studioFor(root).studio) : null) ?? worthHeld(root, opts);
+            if (held) {
+                if (opts.json)
+                    io.log(JSON.stringify({ ok: false, waiting: true, says: held.says }, null, 2));
+                else
+                    u.summary('fail', `not locked: ${held.says}`);
+                return EXIT.fail;
+            }
+            const l = lockDesign(root, { version: opts.version, override: opts.override });
+            if (opts.json) {
+                io.log(JSON.stringify(l, null, 2));
+                return EXIT.pass;
+            }
+            const sig = l.wow?.picks.find((p) => p.role === 'signature');
+            u.item(sig ? 'pass' : 'warn', sig ? `wow: the signature ${sig.id}${sig.expression ? ` ("${sig.expression}")` : ''} and ${l.wow.picks.length - 1} more, pinned with the design` : 'wow: no signature picked before the lock', sig ? (l.wow.problems.join('; ') || 'each pick is a moment a check reads (funtools wow check)') : 'funtools wow lists the card\'s catalogue; wow pick <id> --signature records it (and checks it against the other games\' ledger)');
+            u.summary('pass', `locked ${l.version} on ${l.date}: ${Object.keys(l.files).length} file(s), ${l.targets.length} target frame(s)${l.override ? ', on the creator\'s call' : ''}; decision ${l.decision} in design/decisions.md`);
+            return EXIT.pass;
+        }
+        if (opts.sub === 'page') {
+            const p = writePage(root);
+            if (opts.json) {
+                io.log(JSON.stringify(p, null, 2));
+                return EXIT.pass;
+            }
+            u.summary('pass', `${p.file}: ${p.parts.join(', ') || 'nothing to show yet'}`);
+            return EXIT.pass;
+        }
+        return status(root, opts, u, io);
+    }
+    catch (e) {
+        u.error(e.message);
+        return EXIT.error;
+    }
+}
+function status(root, opts, u, io) {
+    const lock = readLock(root);
+    const wr = existsSync(join(root, 'funpixel.json')) && existsSync(join(root, 'design')) ? recordWorth(root, { now: opts.now, env: opts.env }) : null;
+    const wg = wr?.read ? worthGate(root, { env: opts.env }) : null;
+    const moved = lock ? drift(root, lock) : [];
+    const next = wg && wg.state !== 'met' ? `worth: ${wg.run}` : !lock ? 'the owner agrees the plan in the chat (`funtools flow ask`, `flow agree --by owner`), which locks it' : moved.length ? 'the design moved since the lock: a new version for the owner to lock' : 'build; the rounds hold the game to the locked targets';
+    if (opts.json) {
+        io.log(JSON.stringify({ lock, drift: moved, worth: wr?.read ? { verdict: wr.read.verdict, supplied: wr.read.supplied.minutes, target: wr.read.target.minutes, gate: wg?.state, question: wr.question } : null, next }, null, 2));
+        return lock && !moved.length ? EXIT.pass : EXIT.not_observed;
+    }
+    u.heading(`greenlight · ${root}`);
+    if (wr?.read)
+        showWorth(u, wr.read, wr.question, root, opts.env);
+    u.item(lock ? (moved.length ? 'warn' : 'pass') : 'not_observed', lock ? `locked ${lock.version} on ${lock.date}${lock.override ? ' (the creator\'s call)' : ''}` : 'not locked', moved.length ? `changed since: ${moved.join(', ')}` : undefined);
+    u.summary(lock && !moved.length ? 'pass' : 'not_observed', `next: ${next}`);
+    return lock && !moved.length ? EXIT.pass : EXIT.not_observed;
+}
+function worthHeld(root, opts) {
+    if (!existsSync(join(root, 'funpixel.json')))
+        return null;
+    const run = recordWorth(root, { now: opts.now, env: opts.env });
+    if (!run.read)
+        return null;
+    const g = worthGate(root, { env: opts.env });
+    if (g.state === 'met')
+        return null;
+    return { says: `${WORTH_TITLE} ${g.says} — ${g.run}` };
+}
+function showWorth(u, w, q, root, env) {
+    u.heading(`${WORTH_TITLE} · ${w.verdict}${w.complete ? '' : ' (an incomplete read: not put to the owner until the plan has its numbers and the genre table)'}`);
+    const sup = w.supplied.minutes, tgt = w.target.minutes;
+    u.item(sup === null ? 'not_observed' : tgt && sup < tgt * 2 / 3 ? 'fail' : tgt && sup < tgt ? 'warn' : 'pass', `the plan's own numbers supply ${sup === null ? 'no length' : `${sup} min`}${w.promised ? ` (it promises ${w.promised})` : ''}; target ${tgt ?? 'none'}${tgt ? ' min' : ''}`, `${w.supplied.says}; ${w.target.says}`);
+    const meta = w.bench.metaShare === null ? '–' : `${Math.round(w.bench.metaShare * 100)}%`;
+    const against = !w.bench.used ? 'no genre table to compare with'
+        : w.scale === 'run' ? `a nugget, set beside the genre's best (${w.bench.used}) count for count, not per minute: ${meta} of them carry a meta`
+            : `the genre's best (${w.bench.used}): a place every ${w.bench.minPerPlace ?? '–'} min, a new thing every ${w.bench.minPerNew ?? '–'} min, ${w.bench.charsPerHour ?? '–'} characters an hour, ${meta} carry a meta`;
+    u.item('note', `this plan: ${w.ours.places} places · ${w.ours.mechanics} verbs/mechanics · ${w.ours.characters} characters · ${w.ours.progression} progression`, against);
+    for (const p of w.problems)
+        u.item('warn', p);
+    for (const a of w.adds.filter((x) => x.count > 0 || x.what === 'numbers'))
+        u.item(w.verdict === 'fits' ? 'note' : 'fail', `add: ${a.says}`);
+    u.item(w.verdict === 'fits' ? 'pass' : 'warn', `verdict: ${w.verdict} — ${w.why}`, w.recommend ? `recommended: ${w.recommend} — ${w.recommendWhy}` : undefined);
+    if (needsOwner(w)) {
+        const g = worthGate(root, { env });
+        u.item(g.state === 'met' ? 'pass' : 'warn', `${q ? `${q} asks the owner` : 'the owner\'s fork'}: ${w.options.map(optionWords).join(' · ')}`, g.says);
+    }
+}
+function worth(root, opts, u, io) {
+    if (!existsSync(join(root, 'funpixel.json'))) {
+        u.summary('not_observed', `${root} is not a game folder (no funpixel.json)`);
+        return EXIT.not_observed;
+    }
+    const now = opts.now ?? new Date();
+    const args = opts.args ?? [];
+    if (args[0] === 'choose') {
+        const r = chooseWorth(root, String(args[1] ?? ''), opts.why ?? '', now);
+        if (opts.json)
+            io.log(JSON.stringify(r, null, 2));
+        else
+            u.summary('pass', `${r.q}: ${r.pick}, recorded with your reason (decision ${r.decision})${r.pick === 'prototype' ? '; the prototype stage is on the path' : ''}`);
+        return EXIT.pass;
+    }
+    if (opts.target !== undefined) {
+        const t = setTarget(root, Number(opts.target), { by: opts.by ?? 'agent', from: opts.from, now });
+        if (!opts.json)
+            u.item('pass', `target: ${t.minutes} min (${t.by}), funpixel.json target_minutes`);
+    }
+    const run = recordWorth(root, { now, env: opts.env });
+    if (!run.read) {
+        u.summary('not_observed', 'no design/GDD.md to read worth on: write the pitch, ## The numbers, ## Content list and ## Worth against the genre (skill funpixel-gdd)');
+        return EXIT.not_observed;
+    }
+    ensurePrototype(root, now);
+    const g = worthGate(root, { env: opts.env });
+    const code = g.state === 'met' ? EXIT.pass : EXIT.fail;
+    if (opts.json) {
+        io.log(JSON.stringify({ ...run.read, question: run.question, asked: run.asked, superseded: run.superseded, gate: g }, null, 2));
+        return code;
+    }
+    showWorth(u, run.read, run.question, root, opts.env);
+    for (const id of run.superseded)
+        u.item('note', `${id} closed: the plan changed since it was asked`);
+    if (run.asked)
+        u.item('warn', `${run.asked} is the owner's to answer, in the chat (${WORTH_TITLE})`, `under the owner's autonomy go only: greenlight worth choose <${run.read.options.join('|')}> --why "<reason>"`);
+    u.summary(g.state === 'met' ? 'pass' : 'fail', g.state === 'met' ? g.says : `${g.says}. Next: ${g.run}`);
+    u.line(`recorded ${WORTH_FILE}`);
+    return code;
+}