hbengine 0.2.3

package/README.md

@@ -0,0 +1,20 @@
+# hbengine
+
+Build, verify and ship House Engine games to [House Studio](https://housestudio.io).
+
+```sh
+npx hbengine connect      # approve in the browser; adds the House Engine tools to Claude Code, Cursor and Codex
+```
+
+Then ask your agent: *"Make me a coin flip game and put it in the sandbox."*
+
+Or by hand:
+
+```sh
+npx hbengine init mygame --template coin
+npx hbengine verify mygame
+npx hbengine upload mygame
+npx hbengine status mygame
+```
+
+`npx hbengine templates` lists what a game can start from; the guide is in the studio's Docs.

package/engine-cli/connect.mjs

@@ -0,0 +1,73 @@
+// The browser handshake of `hbengine connect`, apart from the machine it runs on: a code
+// from the portal, a poll until an owner or developer approves, and the approving studio
+// confirmed before the key is kept (declined, the portal revokes it). Everything that
+// touches the world comes in as an argument, so a test drives it without a portal.
+export const POLL_MS = 2000; // between polls
+export const GIVE_UP_MS = 10 * 60 * 1000; // the code's life on the portal
+export const RETRIES = 5; // answers that are nobody's fault, in a row, before giving up
+
+// One form POST: the status and the JSON body ({} when there is none). A network error throws.
+async function call(fetch, url, form) {
+    const r = await fetch(url, { method: 'POST', body: new URLSearchParams(form) });
+    const body = await r.json().catch(() => ({}));
+    return { status: r.status, body };
+}
+
+// Until the key arrives. A 5xx, a 429 or no answer at all is a gateway hiccup or a replica
+// restarting: tried again a few times; any other non-200 is final, the code is gone.
+async function poll(fetch, portal, code, device, sleep, now) {
+    let transient = 0;
+    for (const until = now() + GIVE_UP_MS; ;) {
+        if (now() > until) throw new Error('Not approved within ten minutes: run hbengine connect again.');
+        await sleep(POLL_MS);
+        let r;
+        try { r = await call(fetch, `${portal}/engine/connect/poll`, { code, device }); } catch (e) { r = { status: 0, body: { error: e.message } }; }
+        if (r.status === 200) return r.body;
+        if (r.status === 202) { transient = 0; continue; }
+        if (r.status === 0 || r.status === 429 || r.status >= 500) {
+            if (++transient >= RETRIES) throw new Error(`The portal did not answer ${RETRIES} times in a row (${r.body.error || 'HTTP ' + r.status}): run hbengine connect again.`);
+            continue;
+        }
+        throw new Error(r.body.error || `${portal}/engine/connect/poll: HTTP ${r.status}`);
+    }
+}
+
+/**
+ * @param {object} o
+ * @param {string} o.portal        the studio platform
+ * @param {string} [o.studio]      --studio: the slug that must approve; without it, the person is asked
+ * @param {Function} [o.fetch]
+ * @param {Function} o.prompt      async (question) => answer; throws when it cannot be answered
+ * @param {Function} [o.sleep]     async (ms)
+ * @param {Function} [o.log]
+ * @param {Function} [o.open]      opens the approve page in a browser
+ * @param {Function} [o.now]
+ * @returns {Promise<{key: string, portal: string, studio: string, slug: string}>}
+ */
+export async function handshake({ portal, studio = '', fetch = globalThis.fetch, prompt, sleep = (ms) => new Promise((r) => setTimeout(r, ms)), log = console.log, open = () => {}, now = Date.now }) {
+    portal = portal.replace(/\/$/, '');
+    const start = await call(fetch, `${portal}/engine/connect`, { studio }).catch((e) => { throw new Error(`${portal}/engine/connect: ${e.message} — is it running?`); });
+    if (start.status !== 200) throw new Error(start.body.error || `${portal}/engine/connect: HTTP ${start.status}`);
+    const { code, device, url } = start.body;
+    log(`\nOpening ${url}\nApprove there. The code is ${code}.\n`);
+    open(url);
+    const got = await poll(fetch, portal, code, device, sleep, now);
+    const name = `${got.studio} (${got.slug})`;
+    // The portal refuses an approval from any other studio than --studio names; an older
+    // portal that ignores it is caught here. Either way nothing is kept without a yes.
+    const decline = () => call(fetch, `${portal}/engine/connect/decline`, { code, device }).then((r) => r.status === 200, () => false);
+    const refused = async (why) => {
+        const revoked = await decline();
+        throw new Error(`${why}: ${revoked ? 'the key was revoked and nothing was saved' : 'nothing was saved; the key could not be revoked from here, an owner can in Developer (AI agent)'}.`);
+    };
+    if (studio) {
+        if (got.slug !== studio) return refused(`Approved by ${name}, not ${studio}`);
+    } else {
+        // A question that cannot be answered (the terminal closed) is no yes either: the
+        // key, already handed to this terminal, is revoked rather than left to no one.
+        let a;
+        try { a = (await prompt(`Connect to ${name}? [y/N] `)).trim().toLowerCase(); } catch (e) { return refused(`Not connected to ${name} (${e.message.replace(/\.$/, '')})`); }
+        if (a !== 'y' && a !== 'yes') return refused(`Not connected to ${name}`);
+    }
+    return got;
+}