hbengine 0.2.3

package/engine-cli/hbengine.mjs

@@ -0,0 +1,565 @@
+#!/usr/bin/env node
+/**
+ * hbengine — a studio's whole workflow in six words.
+ *
+ *   hbengine init <dir> [--template coin|dice|slot|tower|wheel] [--slug name]
+ *   hbengine verify  [dir]    the math, by the engine's own verifier: RTP per bet, the hash
+ *   hbengine lint    [dir]    the bundle: budgets, staged loading, forbidden code
+ *   hbengine dev     [dir]    play the bundle inside the real shell against the sandbox
+ *   hbengine test    [dir]    offline: the upload's checks on desktop and phone sizes (Chrome)
+ *   hbengine pack    [dir]    verify + lint, then the .tgz an upload takes (math/, bundle/) to hand over
+ *   hbengine upload  [dir]    verify + lint, then the version goes to the portal, which
+ *                             registers it with the sandbox and plays the conformance run
+ *   hbengine status  [dir]    every version of the game and its state
+ *   hbengine stats   [dir]    rounds, turnover, GGR and RTP by coin, last 30 days, and the shell's counts
+ *   hbengine store   [dir]    the store page from store.json (and tile.png/.webp, 3:4) to the dashboard
+ *   hbengine submit  [dir]    the newest version that passed every check, to review
+ *   hbengine live    [dir]    the newest approved version, live (an owner's key)
+ *   hbengine preflight [dir]  the review checklist items a machine can check, on the newest version
+ *   hbengine review  [dir]    the review: every thread Housebets raised, open must-fix first
+ *   hbengine reply   [dir] --thread <id> --message "<what you changed>" [--fixed]   (4000 characters at most)
+ *   hbengine feedback [dir] --message "<what happened>" [--kind bug|question|idea|feedback] [--subject "<one line>"]
+ *                             a ticket to Housebets (the game in dir, if it is a project, goes with it);
+ *                             --ticket <id> [--close] adds to one instead (8000 characters at most)
+ *   hbengine tickets          the studio's tickets and Housebets' answers
+ *   hbengine connect [url] [--studio <slug>]
+ *                             approve in the browser, confirm the studio, keep the key, add the MCP tools to Claude Code, Cursor, Codex
+ *   hbengine login   [url]    keep a studio API key (from the dashboard: Developer)
+ *   hbengine mcp              the MCP server (what connect adds to the agents)
+ *   hbengine version          this hbengine's version (a newer one on npm is said after any command)
+ *   hbengine templates        what init can start from
+ *
+ * A project is a directory with math/, bundle/ and hbengine.json
+ * ({slug, portal, rgs}). Nothing here decides anything: verify asks the
+ * engine, lint runs the upload's scan, upload asks the portal. What passes
+ * here passes there, because it is the same code.
+ *
+ * With a key (hbengine login, or HBENGINE_KEY and HBENGINE_PORTAL) the
+ * portal is the studio platform's API; without one, the local pipeline.
+ * Offline (the kit), verify and dev start the kit's engine-dev: the
+ * engine's own maths and round rules on this machine, play money.
+ */
+import { execFileSync, spawn, spawnSync } from 'node:child_process';
+import { chmodSync, cpSync, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { createInterface } from 'node:readline/promises';
+import { handshake } from './connect.mjs';
+import { TEMPLATES } from './templates.mjs';
+
+const PKG = new URL('..', import.meta.url).pathname;
+const [cmd, ...rest] = process.argv.slice(2);
+// Flags that stand alone; every other --flag takes the word after it as its value.
+const BOOLEAN = new Set(['--fixed', '--close']);
+const takesValue = (i) => i >= 0 && rest[i].startsWith('--') && !BOOLEAN.has(rest[i]);
+const opt = (k, d) => { const i = rest.findIndex((a, j) => a === '--' + k && !takesValue(j - 1)); return i >= 0 ? rest[i + 1] : d; };
+const flag = (k) => rest.some((a, j) => a === '--' + k && !takesValue(j - 1));
+// The directory is the one word that is neither a flag nor a flag's value.
+const dir = resolve(rest.filter((a, i) => !a.startsWith('--') && !takesValue(i - 1))[0] || '.');
+const DEFAULTS = { portal: 'http://127.0.0.1:8860', rgs: 'http://127.0.0.1:8090', site: process.env.ENGINE_SITE || 'http://localhost:3000' };
+const CREDENTIALS = join(homedir(), '.hbengine', 'credentials');
+// The studio platform when neither the command nor HBENGINE_PORTAL names one (studio/render.go cliPortal).
+// The studio platform: House Studio, unless HBENGINE_PORTAL or a URL on the
+// command names another (Housebets' own testing).
+const PORTAL = process.env.HBENGINE_PORTAL || 'https://housestudio.io';
+// macOS tar otherwise adds AppleDouble `._*` entries; the portal intentionally
+// rejects those metadata files at the upload boundary.
+const TAR_ENV = { ...process.env, COPYFILE_DISABLE: '1' };
+// This hbengine's version: the published package's (npm's hbengine/package.json, one level up);
+// a checkout is "dev", which neither names a release to the portal nor looks for a newer one.
+const VERSION = (() => {
+    try {
+        const p = JSON.parse(readFileSync(join(PKG, 'package.json'), 'utf8'));
+        if (p.name === 'hbengine' && typeof p.version === 'string' && p.version) return p.version;
+    } catch { /* a checkout */ }
+    return 'dev';
+})();
+// Every call to the portal names this hbengine, so the dashboard can say when a studio's tools are behind.
+const UA = { 'User-Agent': `hbengine/${VERSION} (${process.env.HBENGINE_VIA === 'mcp' ? 'mcp' : 'cli'}; node ${process.version})` };
+// A newer hbengine on npm, looked for at most once a day (~/.hbengine/update.json) and said when
+// the command ends: in the terminal, and through the MCP tools to the agent, which tells its user.
+const UPDATE = join(homedir(), '.hbengine', 'update.json');
+const newerThan = (a, b) => {
+    const x = a.split('.').map(Number), y = b.split('.').map(Number);
+    for (let i = 0; i < 3; i++) if ((x[i] || 0) !== (y[i] || 0)) return (x[i] || 0) > (y[i] || 0);
+    return false;
+};
+let newer = null;
+if (VERSION !== 'dev' && !process.env.HBENGINE_NO_UPDATE_CHECK && cmd !== 'mcp' && cmd !== 'version') {
+    (async () => {
+        let seen = {};
+        try { seen = JSON.parse(readFileSync(UPDATE, 'utf8')); } catch { /* first look */ }
+        let latest = seen.latest;
+        if (typeof latest !== 'string' || !(Date.now() - (seen.at || 0) < 24 * 3600 * 1000)) {
+            const r = await fetch('https://registry.npmjs.org/hbengine/latest', { signal: AbortSignal.timeout(2000) }).catch(() => null);
+            const j = r && r.ok ? await r.json().catch(() => null) : null;
+            if (j && typeof j.version === 'string' && /^\d+\.\d+\.\d+$/.test(j.version)) {
+                latest = j.version;
+                try { mkdirSync(dirname(UPDATE), { recursive: true, mode: 0o700 }); writeFileSync(UPDATE, JSON.stringify({ latest, at: Date.now() }) + '\n'); } catch { /* a read-only home: look again next time */ }
+            }
+        }
+        if (typeof latest === 'string' && newerThan(latest, VERSION)) newer = latest;
+    })().catch(() => {});
+    process.on('exit', () => {
+        if (newer) console.error(`\nhbengine ${newer} is out (you have ${VERSION}): restart your agent (it takes the newest when it starts), or npm i -g hbengine@latest if you installed it.`);
+    });
+}
+const login = () => {
+    if (process.env.HBENGINE_KEY) return { key: process.env.HBENGINE_KEY, portal: PORTAL };
+    return existsSync(CREDENTIALS) ? JSON.parse(readFileSync(CREDENTIALS, 'utf8')) : null;
+};
+
+const fail = (msg) => { console.error(msg); process.exit(1); };
+// A project is hbengine.json beside math/ and bundle/; a bare pack (an
+// example) is a project too, named by its manifest.
+// A project may come from someone else: its slug names files, so it is checked.
+const SLUG = /^[a-z0-9][a-z0-9-]{1,23}$/;
+const project = () => {
+    const f = join(dir, 'hbengine.json');
+    const manifest = join(dir, 'math', 'manifest.json');
+    if (!existsSync(f) && !existsSync(manifest)) fail(`${dir} has no hbengine.json and no math/manifest.json (hbengine init makes a project)`);
+    const p = existsSync(f) ? { ...DEFAULTS, ...JSON.parse(readFileSync(f, 'utf8')) } : { ...DEFAULTS, slug: JSON.parse(readFileSync(manifest, 'utf8')).game };
+    if (typeof p.slug !== 'string' || !SLUG.test(p.slug)) fail(`slug ${JSON.stringify(p.slug)}: lowercase letters, digits and dashes, 2–24`);
+    return p;
+};
+// The games API: the studio platform's with a key, else the local pipeline's.
+const games = (p) => {
+    const l = login();
+    return l ? { base: l.portal.replace(/\/$/, '') + '/engine/portal/v1/games', auth: { Authorization: 'Bearer ' + l.key } } : { base: p.portal + '/api/games', auth: {} };
+};
+const get = async (url, auth = {}) => {
+    const r = await fetch(url, { headers: { ...UA, ...auth } }).catch((e) => fail(`${url}: ${e.message} — is it running?`));
+    const j = await r.json().catch(() => fail(`${url}: HTTP ${r.status}`));
+    if (!r.ok) fail(j.error || `${url}: HTTP ${r.status}`);
+    return j;
+};
+// A 429 or 503 with Retry-After is the studio saying its pipeline is busy
+// (another pack in the verifier, the play-tests full), not that the pack is
+// bad: the call is made again after that wait, three times at most.
+const post = async (url, body, type = 'application/json', auth = {}, tries = 3) => {
+    const r = await fetch(url, { method: 'POST', headers: { 'Content-Type': type, ...UA, ...auth }, body }).catch((e) => fail(`${url}: ${e.message} — is it running?`));
+    const text = await r.text();
+    let j;
+    try { j = JSON.parse(text); } catch { fail(`${url}: HTTP ${r.status} ${text.slice(0, 120)}`); }
+    const after = Number(r.headers.get('retry-after'));
+    if ((r.status === 429 || r.status === 503) && after > 0 && tries > 1) {
+        console.error(`${j.error || `${url}: HTTP ${r.status}`} — trying again in ${after} s`);
+        await new Promise((resolve) => setTimeout(resolve, Math.min(after, 60) * 1000));
+        return post(url, body, type, auth, tries - 1);
+    }
+    if (!r.ok) fail(j.error || `${url}: HTTP ${r.status}`);
+    return j;
+};
+
+async function init() {
+    const template = opt('template', 'coin');
+    if (!TEMPLATES[template]) fail(`--template: one of ${Object.keys(TEMPLATES).join(', ')}`);
+    const slug = opt('slug', template);
+    if (!SLUG.test(slug)) fail(`--slug ${slug}: lowercase letters, digits and dashes, 2–24`);
+    if (existsSync(dir)) fail(`${dir} exists`);
+    const from = join(PKG, 'engine-examples', template);
+    if (!existsSync(from)) fail(`no template ${template}`);
+    cpSync(from, dir, { recursive: true });
+    // math-kit/ is a link in the repo; a project gets its own copy (no tests).
+    const kit = join(dir, 'math-kit');
+    if (existsSync(kit) && lstatSync(kit).isSymbolicLink()) {
+        unlinkSync(kit);
+        cpSync(join(PKG, 'engine-math'), kit, { recursive: true, filter: (f) => !f.endsWith('.test.mjs') });
+    }
+    writeFileSync(join(dir, 'hbengine.json'), JSON.stringify({ slug, ...DEFAULTS }, null, 2) + '\n');
+    // The store page, to fill in and send with hbengine store.
+    if (!existsSync(join(dir, 'store.json'))) writeFileSync(join(dir, 'store.json'), JSON.stringify({ title: slug, category: 'other', description: '', features: [], tags: [], languages: ['en'], rules: { en: '' } }, null, 2) + '\n');
+    // A template whose tables are generated (the maths kit) makes them for this slug now.
+    if (!existsSync(join(dir, 'math', 'manifest.json'))) {
+        console.log('making the maths (math/gen.mjs)…');
+        const g = spawnSync('node', [join('math', 'gen.mjs'), slug], { cwd: dir, stdio: 'inherit' });
+        if (g.status !== 0) fail('math/gen.mjs failed');
+    } else {
+        // The pack is the game's: its slug, and its tables named after it.
+        const manifest = join(dir, 'math', 'manifest.json');
+        const m = JSON.parse(readFileSync(manifest, 'utf8'));
+        m.game = slug;
+        const rename = (t) => (t && t.startsWith(template) ? slug + t.slice(template.length) : t);
+        for (const f of readdirSync(join(dir, 'math'))) if (f.endsWith('.tsv') && rename(f) !== f) renameSync(join(dir, 'math', f), join(dir, 'math', rename(f)));
+        for (const mode of m.modes) {
+            mode.table = rename(mode.table);
+            for (const step of mode.steps || []) step.table = rename(step.table);
+        }
+        writeFileSync(manifest, JSON.stringify(m, null, 2) + '\n');
+    }
+    console.log(`${dir}: a ${template} game as "${slug}".\nNext: edit math/ and bundle/, then hbengine verify and hbengine dev; hbengine pack makes the file to hand over (or hbengine upload with a studio key).`);
+}
+
+// The kit's offline sandbox: when nothing answers at rgs, start engine-dev
+// (bin/engine-dev-<os>-<arch>) on this project's math. True when the sandbox
+// is engine-dev; its process, if this command started it.
+const ENGINE_DEV = join(PKG, '..', 'bin', `engine-dev-${process.platform}-${process.arch}${process.platform === 'win32' ? '.exe' : ''}`);
+const answers = (url) => fetch(url, { method: 'HEAD' }).then((r) => r.status).catch(() => 0);
+async function sandbox(rgs) {
+    const at = await answers(`${rgs}/dev/launch`);
+    if (at) return { offline: at === 200 };
+    if (!existsSync(ENGINE_DEV)) return { offline: false };
+    // engine-dev listens on this machine only, whatever a project's hbengine.json says.
+    const host = new URL(rgs).hostname;
+    if (host !== '127.0.0.1' && host !== 'localhost') fail(`rgs ${rgs}: engine-dev runs on 127.0.0.1 only`);
+    const child = spawn(ENGINE_DEV, ['--math', join(dir, 'math'), '--addr', new URL(rgs).host], { stdio: 'ignore' });
+    for (let i = 0; i < 50 && !(await answers(`${rgs}/dev/launch`)); i++) await new Promise((r) => setTimeout(r, 100));
+    return { offline: true, child };
+}
+
+async function verify() {
+    const { rgs } = project();
+    const box = login() ? {} : await sandbox(rgs);
+    process.on('exit', () => box.child?.kill());
+    const mathDir = join(dir, 'math');
+    const files = Object.fromEntries(readdirSync(mathDir, { withFileTypes: true }).filter((e) => e.isFile()).map((e) => [e.name, readFileSync(join(mathDir, e.name), 'utf8')]));
+    // With a key the studio platform asks the engine (CI has no sandbox); without, the local sandbox.
+    const l = login();
+    const r = l ? await post(`${l.portal.replace(/\/$/, '')}/engine/portal/v1/verify`, JSON.stringify({ files }), 'application/json', { Authorization: 'Bearer ' + l.key })
+        : await post(`${rgs}/engine/v1/verify`, JSON.stringify({ files }));
+    if (!r.ok) fail('math does not verify:\n  ' + r.errors.join('\n  '));
+    console.log(`math ok  hash ${r.hash}`);
+    const pct = (bp) => (Number(bp) / 100).toFixed(4) + '%';
+    for (const m of r.report.modes) for (const b of m.bets) console.log(`  ${m.id}/${b.id}: RTP ${pct(b.rtp)}  hit ${pct(b.hitRate)}  max ${b.maxMult}×${b.stops ? '  stops ' + b.stops.map(pct).join(' ') : ''}`);
+    for (const w of r.report.warnings || []) console.log('  warning: ' + w);
+    box.child?.kill();
+}
+
+function lint() {
+    const r = spawnSync('node', [join(PKG, 'engine-conformance', 'scan.mjs'), join(dir, 'bundle')], { encoding: 'utf8' });
+    process.stdout.write(r.stdout + r.stderr);
+    if (r.status !== 0) process.exit(1);
+}
+
+async function dev() {
+    const { slug, portal, rgs } = project();
+    const box = await sandbox(rgs);
+    if (box.offline) {
+        // engine-dev reads math/ at every launch: edit either, reload the page.
+        return spawn('node', [join(PKG, 'engine-conformance', 'run.mjs'), join(dir, 'bundle'), '--slug', slug, '--game-id', '0', '--rgs', rgs, '--dev'], { stdio: 'inherit' });
+    }
+    // engine-dev ships with the offline kit, not with npm: on the platform the upload is the sandbox.
+    if (login() && !(await answers(`${rgs}/dev/launch`))) fail('hbengine dev needs a sandbox on this machine (the offline kit). With a studio key, hbengine upload plays the game in the platform\'s sandbox and prints the link.');
+    // The sandbox plays your local bundle on the math it already has: the
+    // first `hbengine upload` registers the game and its pack there.
+    if (!(await fetch(`${rgs}/engine/v1/math/${slug}`).then((r) => r.ok).catch(() => fail(`${rgs}: the sandbox RGS is not reachable`)))) fail(`the sandbox does not know "${slug}" yet: run hbengine upload once, then hbengine dev plays your local bundle`);
+    const g = await post(`${portal}/api/games`, JSON.stringify({ slug })); // the local pipeline: dev plays locally
+    spawn('node', [join(PKG, 'engine-conformance', 'run.mjs'), join(dir, 'bundle'), '--slug', slug, '--game-id', String(g.id), '--rgs', rgs, '--dev'], { stdio: 'inherit' });
+}
+
+async function upload() {
+    await verify();
+    lint();
+    const p = project();
+    const { slug, site } = p;
+    const { base, auth } = games(p);
+    const g = await post(base, JSON.stringify({ slug, title: p.title || slug }), 'application/json', auth);
+    const tgz = execFileSync('tar', ['-czf', '-', 'math', 'bundle'], { cwd: dir, env: TAR_ENV, maxBuffer: 200 * 1024 * 1024 });
+    let v = await post(`${base}/${slug}/uploads`, tgz, 'application/gzip', auth);
+    console.log(`version ${v.n} ${v.state}${v.hash ? '  math ' + v.hash.slice(0, 12) : ''}`);
+    if (v.state === 'failed') fail(report(v));
+    console.log('the sandbox plays it now on desktop and phone (about two minutes; hbengine status shows the state meanwhile)');
+    process.stdout.write('conformance run ');
+    for (let waited = 0; v.run && v.run.detail === 'running'; waited += 2) {
+        if (waited > 600) fail('\nthe run is still going after ten minutes: hbengine status');
+        await new Promise((r) => setTimeout(r, 2000));
+        process.stdout.write('.');
+        v = await get(`${base}/${slug}/uploads/${v.n}`, auth);
+    }
+    console.log('\n' + report(v));
+    if (v.state !== 'sandbox') process.exit(1);
+    // The local site's address means nothing to a studio on the platform: there, the game's own link.
+    const play = login() ? g.play : `${site}/games/housebets-engine-${slug}`;
+    if (play) console.log(`play it: ${play}  (id ${g.id})`);
+    if (g.dashboard) console.log(`submit it for review: ${g.dashboard}?tab=versions`);
+}
+
+function report(v) {
+    const lines = [];
+    if (v.verify && !v.verify.ok) lines.push(...v.verify.errors.map((e) => 'math: ' + e));
+    if (v.scan) for (const f of v.scan.findings) lines.push(`${f.level.toUpperCase()} ${f.rule}${f.file ? ' ' + f.file : ''}: ${f.detail}`);
+    if (v.run) for (const c of v.run.checks || []) lines.push(`${c.status === 'skipped' ? 'skip' : !c.ok ? 'FAIL' : c.status === 'warning' ? 'warn' : 'ok  '} ${c.size.padEnd(8)} ${c.rule.padEnd(8)} ${c.detail}`);
+    if (v.run && v.run.detail && v.run.detail !== 'running' && !v.run.checks?.length) lines.push('run: ' + v.run.detail);
+    return `${v.state}\n` + lines.map((l) => '  ' + l).join('\n');
+}
+
+async function status() {
+    const p = project();
+    const { base, auth } = games(p);
+    const g = await get(`${base}/${p.slug}`, auth);
+    console.log(`${p.slug}  id ${g.id}${g.state ? '  ' + g.state : ''}${g.play ? '  play ' + g.play : ''}${g.dashboard ? '\n  ' + g.dashboard : ''}`);
+    const review = { pending: 'in review', approved: 'approved', returned: 'returned with notes' };
+    for (const v of g.uploads) console.log(`  v${v.n}  ${v.at}  ${v.state}${v.hash ? '  math ' + v.hash.slice(0, 12) : ''}${review[v.review] ? '  ' + review[v.review] : ''}${g.liveVersion === v.n ? '  LIVE' : ''}`);
+    const approved = [...g.uploads].reverse().find((v) => v.review === 'approved');
+    if (approved && approved.n !== g.liveVersion && approved.n > (g.liveVersion || 0)) console.log(`v${approved.n} is approved and not live yet: hbengine live puts it live.`);
+    if (g.liveVersion && g.onSite === false) console.log('Live on the engine; Housebets opens it on the site next and emails you when players can find it.');
+}
+
+async function stats() {
+    const p = project();
+    const l = login() || fail('hbengine stats reads the studio platform: hbengine login first');
+    const r = await get(`${games(p).base}/${p.slug}/stats`, games(p).auth);
+    console.log(`${p.slug}  ${r.From} … ${r.To}`);
+    // The shell's counts (never text): a launch per open, an error per engine.reportError or uncaught
+    // error, a round left open per page closed on one. Before the rounds: a game that fails at every
+    // launch has launches and errors and no round, and that is when the counts matter.
+    const s = r.Telemetry;
+    if (s && (s.Boot || s.Error || s.Abandon || s.Slow)) console.log(`  shell  launches ${s.Boot}  errors ${s.Error}  rounds left open ${s.Abandon}${s.Slow ? `  slow starts ${s.Slow}` : ''}`);
+    if (!r.Totals || !r.Totals.length) return console.log('  no rounds');
+    // Percentages cut, never rounded up; the band only where it means something (as the dashboard).
+    const pct = (x) => (Math.floor(x * 100 + 1e-9) / 100).toFixed(2) + '%';
+    for (const t of r.Totals) console.log(`  ${t.Currency.padEnd(5)} rounds ${t.Rounds}  turnover ${t.Turnover}  GGR ${t.GGR.toFixed(8)}  RTP ${pct(t.RTP)}${t.Expected ? `  (expected ${pct(t.Expected)}${t.Band < 10 ? ` ± ${pct(t.Band)}` : ', too few rounds to compare yet'})` : ''}`);
+}
+
+async function loginCmd() {
+    const portal = (rest.find((a) => /^https?:\/\//.test(a)) || PORTAL).replace(/\/$/, '');
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    const key = (await rl.question(`API key for ${portal} (dashboard → Developer): `)).trim();
+    rl.close();
+    if (!/^hbk_[\w-]{20,}$/.test(key)) fail('that is not an API key (hbk_…)');
+    const list = await get(`${portal}/engine/portal/v1/games`, { Authorization: 'Bearer ' + key });
+    mkdirSync(join(homedir(), '.hbengine'), { recursive: true, mode: 0o700 });
+    writeFileSync(CREDENTIALS, JSON.stringify({ portal, key }) + '\n', { mode: 0o600 });
+    chmodSync(CREDENTIALS, 0o600);
+    console.log(`signed in to ${portal}: ${list.length} game(s). The key is in ${CREDENTIALS}.`);
+}
+
+// The browser handshake (connect.mjs): a code, an Approve in the dashboard, the key, and
+// the approving studio confirmed before anything is written. Then every agent on this
+// machine gets the MCP tools, which read the key from the credentials file.
+async function connect() {
+    const portal = (rest.find((a) => /^https?:\/\//.test(a)) || PORTAL).replace(/\/$/, '');
+    const studio = opt('studio', '');
+    // An agent runs this with no terminal to answer the question in: it names the studio
+    // instead, and hears so now, before a code is made and someone approves it.
+    if (!studio && !process.stdin.isTTY) fail('No terminal to confirm the studio in: run hbengine connect --studio <slug> (Organisation, Profile shows the slug).');
+    const opener = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'explorer' : 'xdg-open';
+    // The terminal closing under the question (Ctrl-D) would leave it unanswered for ever and
+    // the process would just end: it is an error instead, and the handshake declines on it.
+    const prompt = (q) => new Promise((resolve, reject) => {
+        const rl = createInterface({ input: process.stdin, output: process.stdout });
+        rl.once('close', () => reject(new Error('the terminal closed before an answer')));
+        rl.question(q).then(resolve, reject).finally(() => rl.close());
+    });
+    const got = await handshake({ portal, studio, prompt, open: (url) => spawn(opener, [url], { stdio: 'ignore', detached: true }).on('error', () => {}).unref() })
+        .catch((e) => fail(e.message));
+    mkdirSync(join(homedir(), '.hbengine'), { recursive: true, mode: 0o700 });
+    writeFileSync(CREDENTIALS, JSON.stringify({ portal: got.portal, key: got.key }) + '\n', { mode: 0o600 });
+    chmodSync(CREDENTIALS, 0o600);
+    // From a checkout, the server beside this file; from npm, the published one.
+    const local = !PKG.includes('node_modules');
+    const server = local ? [process.execPath, join(PKG, 'engine-mcp', 'server.mjs')] : ['npx', '-y', 'hbengine', 'mcp'];
+    const added = [];
+    const has = (bin) => spawnSync(process.platform === 'win32' ? 'where' : 'which', [bin], { stdio: 'ignore' }).status === 0;
+    if (has('claude')) {
+        spawnSync('claude', ['mcp', 'remove', 'house-engine', '-s', 'user'], { stdio: 'ignore' });
+        if (spawnSync('claude', ['mcp', 'add', 'house-engine', '-s', 'user', '--', ...server], { stdio: 'ignore' }).status === 0) added.push('Claude Code');
+    }
+    if (has('codex')) {
+        spawnSync('codex', ['mcp', 'remove', 'house-engine'], { stdio: 'ignore' });
+        if (spawnSync('codex', ['mcp', 'add', 'house-engine', '--', ...server], { stdio: 'ignore' }).status === 0) added.push('Codex');
+    }
+    const cursor = join(homedir(), '.cursor');
+    if (existsSync(cursor)) {
+        const f = join(cursor, 'mcp.json');
+        let cfg = {};
+        let readable = true;
+        if (existsSync(f)) try { cfg = JSON.parse(readFileSync(f, 'utf8')); } catch { readable = false; }
+        if (readable) {
+            cfg.mcpServers = { ...cfg.mcpServers, 'house-engine': { command: server[0], args: server.slice(1) } };
+            writeFileSync(f, JSON.stringify(cfg, null, 2) + '\n');
+            added.push('Cursor');
+        } else {
+            console.log(`${f} is not plain JSON (comments or a trailing comma?), so it was left alone. Add this under "mcpServers":\n  "house-engine": ${JSON.stringify({ command: server[0], args: server.slice(1) })}\n`);
+        }
+    }
+    console.log(`Connected to ${got.studio} (${got.slug}).`);
+    console.log(added.length ? `House Engine tools added to ${added.join(', ')}. Restart it, then ask: "Make me a coin flip game and put it in the sandbox."`
+        : `No agent found. Add this MCP server to yours: ${server.join(' ')}`);
+}
+
+async function storeCmd() {
+    const p = project();
+    login() || fail('hbengine store sends to the studio platform: hbengine login first');
+    const { base, auth } = games(p);
+    const f = join(dir, 'store.json');
+    if (!existsSync(f)) fail(`${f}: {title, category, description, features, tags, languages, rules{en}}`);
+    const r = await fetch(`${base}/${p.slug}/store`, { method: 'PUT', headers: { 'Content-Type': 'application/json', ...UA, ...auth }, body: readFileSync(f) });
+    const j = await r.json().catch(() => ({}));
+    if (r.status === 404) fail(`${p.slug} is not on the studio platform yet: hbengine upload creates it`);
+    if (!r.ok) fail(j.error || `HTTP ${r.status}`);
+    const tile = ['tile.png', 'tile.webp'].map((t) => join(dir, t)).find(existsSync);
+    let kept = ''; // why the tile stayed as it was
+    if (tile) {
+        const t = await fetch(`${base}/${p.slug}/tile`, { method: 'PUT', headers: { ...UA, ...auth }, body: readFileSync(tile) });
+        const why = t.ok ? '' : (await t.json().catch(() => ({}))).error || `HTTP ${t.status}`;
+        // 409: the game is live and its tile is the one review saw (until Housebets reset it).
+        // The page is saved; the tile staying is said, not an error, or every store of a live game fails.
+        if (t.status === 409) kept = why;
+        else if (!t.ok) fail('tile: ' + why);
+    }
+    const missing = tile ? (j.missing || []).filter((m) => m !== 'a tile') : j.missing || [];
+    console.log(`store page saved${tile && !kept ? ' with the tile' : ''}.${kept ? ' Tile unchanged: ' + kept : ''}${missing.length ? ' Before review it needs: ' + missing.join(', ') + '.' : ' Ready for review: hbengine submit.'}`);
+}
+
+async function submit() {
+    const p = project();
+    login() || fail('hbengine submit sends to the studio platform: hbengine login first');
+    const { base, auth } = games(p);
+    const g = await get(`${base}/${p.slug}`, auth);
+    const v = [...(g.uploads || [])].reverse().find((u) => u.state === 'sandbox') || fail('no version has passed every check yet: hbengine upload');
+    const r = await post(`${base}/${p.slug}/uploads/${v.n}/submit`, '{}', 'application/json', auth);
+    console.log(`version ${v.n} is in review. ${r.dashboard}\nHousebets emails you the verdict; once it is approved, hbengine live puts it live.`);
+}
+
+// The newest approved version, live: the round server and the front end switch to it within
+// seconds. Going live is an owner's, so the key must be one an owner made.
+async function live() {
+    const p = project();
+    login() || fail('hbengine live talks to the studio platform: hbengine connect first');
+    const { base, auth } = games(p);
+    const g = await get(`${base}/${p.slug}`, auth);
+    const ups = g.uploads || [];
+    const v = [...ups].reverse().find((u) => u.review === 'approved');
+    if (!v) {
+        const waiting = [...ups].reverse().find((u) => u.review === 'pending');
+        fail(waiting ? `v${waiting.n} is still in review: Housebets emails you when it is approved, then hbengine live` : 'no version is approved yet: hbengine submit sends the newest that passed every check to review');
+    }
+    if (g.liveVersion && v.n <= g.liveVersion) return console.log(`v${g.liveVersion} is live; no newer version is approved.`);
+    const r = await post(`${base}/${p.slug}/uploads/${v.n}/live`, '{}', 'application/json', auth);
+    console.log(`${p.slug} v${r.version} is live. ${r.dashboard}` + (g.liveVersion ? '' : '\nPlayers find it on Housebets once Housebets switches its catalogue page on; you get an email when it is.'));
+}
+
+// The review, as Housebets left it: threads (must-fix first), what each asks, the replies so far.
+async function review() {
+    const p = project();
+    login() || fail('hbengine review reads the studio platform: hbengine login first');
+    const { base, auth } = games(p);
+    const r = await get(`${base}/${p.slug}/review`, auth);
+    const ts = r.threads || [];
+    const rank = (t) => (t.severity === 'must' && t.state === 'open' ? 0 : t.state === 'open' ? 1 : t.state === 'fixed' ? 2 : 3);
+    console.log(`${p.slug}  review: ${r.mustFixOpen} must-fix not resolved (${r.markedFixed} marked fixed), ${r.suggestionsOpen} suggestions open\n  ${r.dashboard}`);
+    if (!ts.length) console.log('  no threads');
+    for (const t of [...ts].sort((a, b) => rank(a) - rank(b))) {
+        console.log(`\n#${t.id}  ${t.severity === 'must' ? 'MUST FIX' : 'suggestion'}  ${t.area}  raised on v${t.version}  ${t.state}${t.fixedIn ? ' (fixed in v' + t.fixedIn + ')' : ''}`);
+        for (const c of t.comments || []) console.log(`  ${c.from === 'housebets' ? 'Housebets' : 'Studio'} (${c.name}): ${c.body.replace(/\n/g, '\n    ')}`);
+    }
+    const open = ts.filter((t) => t.severity === 'must' && t.state === 'open');
+    if (open.length) console.log(`\nFix each open must-fix thread in the project, then hbengine upload and hbengine submit: the submitted version is marked as fixing them, and Housebets checks each one. To ask the reviewer something: hbengine reply --thread <id> --message "…".`);
+    const failed = (r.checklist || []).filter((c) => c.result === 'fail');
+    if (failed.length) console.log(`\nChecklist items that failed on v${r.checklistVersion}:\n` + failed.map((c) => `  ${c.area}: ${c.check}`).join('\n'));
+}
+
+// What a reviewer would send back that a machine can see already: run it before hbengine submit.
+async function preflight() {
+    const p = project();
+    login() || fail('hbengine preflight reads the studio platform: hbengine login first');
+    const { base, auth } = games(p);
+    const r = await get(`${base}/${p.slug}/preflight`, auth);
+    console.log(`${p.slug} v${r.version}  pre-flight: ${r.passed} passed, ${r.failed} failed`);
+    for (const i of r.items) {
+        const mark = { pass: 'ok  ', fail: 'FAIL', wait: '... ' }[i.state] || '    ';
+        console.log(`  ${mark} ${i.area.padEnd(10)} ${i.state === 'reviewer' ? i.check + '  (the reviewer checks)' : i.detail}`);
+    }
+    if (r.rulesFacts) console.log(`\nThe rules must quote (from the verified maths):\n  ${r.rulesFacts.replace(/\n/g, '\n  ')}`);
+    if (r.failed) process.exitCode = 1;
+}
+
+async function reply() {
+    const p = project();
+    login() || fail('hbengine reply writes to the studio platform: hbengine login first');
+    const thread = opt('thread') || fail('--thread <id>: the number hbengine review shows');
+    const message = opt('message', '');
+    const fixed = flag('fixed');
+    if (!message && !fixed) fail('--message "what you changed", and --fixed when the project has the change');
+    // The platform refuses more; said here with the count, before anything is sent.
+    if (message.length > 4000) fail(`the reply is over 4000 characters (${message.length}): say less, or split it over two replies`);
+    const { base, auth } = games(p);
+    await post(`${base}/${p.slug}/review/threads/${encodeURIComponent(thread)}`, JSON.stringify({ body: message, fixed }), 'application/json', auth);
+    console.log(`replied on #${thread}${fixed ? ', marked fixed: upload the version that has it, then hbengine submit' : ''}.`);
+}
+
+// Feedback and support: a ticket to Housebets (a bug, a question, an idea, what you think), or a
+// message on one. What goes with it: this hbengine's version, node, the OS and the project's game,
+// never a key (the platform removes any it finds in the message too).
+const TICKET_MAX = 8000;
+const KINDS = ['bug', 'question', 'idea', 'feedback'];
+const support = () => {
+    const l = login() || fail('hbengine feedback talks to the studio platform: hbengine connect first');
+    return { base: l.portal.replace(/\/$/, '') + '/engine/portal/v1/support', auth: { Authorization: 'Bearer ' + l.key } };
+};
+
+async function feedback() {
+    const { base, auth } = support();
+    const message = opt('message', '');
+    const ticket = opt('ticket');
+    const close = flag('close');
+    if (!message && !(ticket && close)) fail('--message "what you did, what happened, what you expected, the exact error"');
+    if (message.length > TICKET_MAX) fail(`the message is over ${TICKET_MAX} characters (${message.length}): put the essentials first, or send the rest with --ticket <id>`);
+    if (ticket) {
+        if (!/^\d+$/.test(ticket)) fail('--ticket <id>: the number hbengine tickets shows');
+        const r = await post(`${base}/${ticket}`, JSON.stringify({ body: message, close }), 'application/json', auth);
+        return console.log(`ticket #${ticket}: ${r.state === 'closed' ? 'closed' : 'sent; Housebets answers by email and in hbengine tickets'}.`);
+    }
+    const kind = opt('kind', 'feedback');
+    if (!KINDS.includes(kind)) fail(`--kind: one of ${KINDS.join(', ')}`);
+    // The game, when the directory is a project.
+    let game = '';
+    try {
+        const s = JSON.parse(readFileSync(join(dir, 'hbengine.json'), 'utf8')).slug;
+        if (typeof s === 'string' && SLUG.test(s)) game = s;
+    } catch { /* not a project: a ticket about no game */ }
+    const context = { hbengine: VERSION, node: process.version, os: `${process.platform} ${process.arch}`, ...(game ? { game } : {}) };
+    const r = await post(base, JSON.stringify({ kind, subject: opt('subject', ''), body: message, game, source: process.env.HBENGINE_VIA === 'mcp' ? 'mcp' : 'cli', context }), 'application/json', auth);
+    console.log(`ticket #${r.id} sent to Housebets${game ? ` (about ${game})` : ''}. The answer comes by email and in hbengine tickets.\n  ${r.url}`);
+}
+
+async function tickets() {
+    const { base, auth } = support();
+    const r = await get(base, auth);
+    const ts = r.tickets || [];
+    if (!ts.length) return console.log('no tickets. hbengine feedback --message "…" opens one.');
+    const word = { open: 'waiting for Housebets', answered: 'ANSWERED', closed: 'closed' };
+    for (const t of ts) {
+        console.log(`\n#${t.id}  ${t.kind}  ${word[t.state] || t.state}${t.game ? '  ' + t.game : ''}  ${t.subject}`);
+        for (const m of t.messages || []) console.log(`  ${m.from === 'housebets' ? 'Housebets' : 'Studio'} (${m.name}): ${m.body.replace(/\n/g, '\n    ')}`);
+    }
+    console.log(`\nTo answer: hbengine feedback --ticket <id> --message "…" (--close when it is solved).\n${r.dashboard}`);
+}
+
+// The upload's conformance run, offline against engine-dev (needs Chrome
+// and playwright-core: npm install playwright-core).
+async function test() {
+    const { slug, rgs } = project();
+    const box = await sandbox(rgs);
+    if (!box.offline) fail(`${rgs} is not engine-dev: with a sandbox, hbengine upload runs these checks`);
+    process.on('exit', () => box.child?.kill());
+    const r = spawnSync('node', [join(PKG, 'engine-conformance', 'run.mjs'), join(dir, 'bundle'), '--slug', slug, '--game-id', '0', '--rgs', rgs], { stdio: 'inherit' });
+    process.exit(r.status ?? 1);
+}
+
+// One file to hand over, after the same checks an upload makes: exactly
+// what an upload accepts (math/ and bundle/); the sha256 lets the receiver
+// check it. The store page travels on its own (hbengine store, or by hand).
+async function pack() {
+    const p = project();
+    await verify();
+    lint();
+    mkdirSync(join(dir, 'dist'), { recursive: true });
+    const out = join(dir, 'dist', `${p.slug}-${new Date().toISOString().slice(0, 10)}.tgz`);
+    execFileSync('tar', ['-czf', out, '-C', dir, 'math', 'bundle'], { env: TAR_ENV });
+    const sum = createHash('sha256').update(readFileSync(out)).digest('hex');
+    const store = ['store.json', 'tile.png', 'tile.webp'].filter((f) => existsSync(join(dir, f)));
+    console.log(`${out}\nsha256 ${sum}\nsend both; the receiver uploads the .tgz in the dashboard (the game's page, New version).` + (store.length ? `\nthe store page is not in it: send ${store.join(' and ')} too.` : ''));
+}
+
+function templates() {
+    for (const [t, about] of Object.entries(TEMPLATES)) console.log(`${t.padEnd(7)} ${about}`);
+}
+
+const mcp = async () => (await import('../engine-mcp/server.mjs')).serve();
+const version = () => console.log(VERSION);
+const commands = { init, verify, lint, dev, test, pack, upload, status, stats, store: storeCmd, submit, live, preflight, review, reply, feedback, tickets, login: loginCmd, connect, mcp, templates, version };
+if (!commands[cmd]) fail('usage: hbengine init|verify|lint|dev|test|pack|upload|status|stats|store|submit|live|preflight|review|reply|feedback|tickets|connect|login|mcp|templates|version [dir]');
+await commands[cmd]();

package/engine-cli/package.json

@@ -0,0 +1 @@
+{ "type": "module" }

package/engine-cli/templates.mjs

@@ -0,0 +1,14 @@
+// What `hbengine init` can start from (packages/engine-examples), and what each is.
+export const TEMPLATES = {
+    coin: 'one bet, two outcomes: the smallest complete game',
+    dice: 'a target per mode, exact RTP on each',
+    slot: 'three reels, every stop combination in the table',
+    lines: 'five reels, paylines, scatters and free spins, built by the maths kit',
+    tumble: 'a 6 × 5 scatter-pays grid with tumbles, free spins with multipliers (the maths kit)',
+    plinko: 'rows and risk levels, each bucket weighted by the binomial',
+    keno: '40 numbers, 10 drawn, 1–10 picks; exact hypergeometric weights',
+    crash: 'a ladder that climbs by itself: cash out before it busts, 99% at every level',
+    mines: 'a 5 × 5 grid, 1–24 mines: reveal tiles, cash out; exact weights per reveal',
+    tower: 'a ladder: climb, cash out, or lose the stake',
+    wheel: 'weighted segments, risk levels as modes',
+};

package/engine-conformance/analyse-worker.mjs

@@ -0,0 +1,12 @@
+// The code analysis of every script in a bundle, for scan.mjs: parsed and
+// walked on a worker thread (bundle.mjs does the work), so a file built to
+// keep a parser busy never holds the event loop of the process that asked (the
+// pipeline serves an API while it scans), and scan.mjs can stop the thread at
+// its deadline. One message back: the findings per file, with what scan.mjs
+// decides at bundle level (minified files against their source maps,
+// WebAssembly against its sources). scan.mjs says what each file is (its
+// `kind`: 'xml', 'html', 'data' or 'script'); the bundle is read as one.
+import { parentPort, workerData } from 'node:worker_threads';
+import { analyseBundle } from './bundle.mjs';
+
+parentPort.postMessage(analyseBundle(workerData.files));