@looop-games/cli 0.1.2

package/lib/inject.mjs

@@ -0,0 +1,78 @@
+// HTML/JS dev-serving transforms — a Node port of the proven logic in
+// looop-core tools/game/dev_server.py, kept behaviour-identical:
+//
+//   * Head injection mirrors the production /g/<slug> serve path
+//     (builder/functions/g/[[path]].ts): window.GAME_SLUG + window.LOOOP_IDENTITY
+//     (classic scripts, so globals exist before any module runs) + the ONE
+//     platform-layer module tag. New platform features are added to
+//     shared/platform/platform.js FEATURES — never here.
+//   * ?v=<mtime> rewriting on <script src> and JS imports busts Chrome's
+//     sticky module cache on edit.
+import { statSync } from 'node:fs';
+import { join, dirname, normalize } from 'node:path';
+
+// MUST match builder/functions/_shared/serve-identity.ts DEV_IDENTITY.
+export const DEV_IDENTITY = { userId: 'dev-local-user', name: 'Dev', color: '#38bdf8' };
+
+export const PLATFORM_URL = '/shared/platform/platform.js';
+
+// JSON safe for an inline <script>: `<` → < so a value containing
+// "</script>" can't terminate the script early.
+function jsJson(value) {
+  return JSON.stringify(value).replaceAll('<', '\\u003c');
+}
+
+export function injectHeadTags(html, slug, { identity = DEV_IDENTITY, platformUrl = PLATFORM_URL } = {}) {
+  const parts = [];
+  if (slug) parts.push(`<script>window.GAME_SLUG = ${jsJson(slug)};</script>`);
+  parts.push(`<script>window.LOOOP_IDENTITY = ${jsJson(identity)};</script>`);
+  parts.push(
+    `<script type="module">import { installPlatform } from "${platformUrl}"; installPlatform();</script>`,
+  );
+  const inject = '\n  ' + parts.join('\n  ');
+  const m = /<head[^>]*>/i.exec(html);
+  if (m) return html.slice(0, m.index + m[0].length) + inject + html.slice(m.index + m[0].length);
+  return parts.join('\n') + '\n' + html;
+}
+
+// Match `import ... from "X"`, `import "X"`, `import("X")`, `export ... from "X"`.
+const JS_IMPORT_RE = /(\b(?:from|import)\s*\(?\s*)(['"])([^'"\n]+?)\2/g;
+// Match <script src="X"> in HTML.
+const HTML_SCRIPT_RE = /(<script\b[^>]*?\bsrc\s*=\s*["'])([^"']+?)(["'])/gi;
+
+// Resolve `relPath` and return `<relPath>?v=<mtime-seconds>` or null.
+// `resolveUrl(urlPath)` maps an absolute URL path through the server's mounts.
+function versionedPath(relPath, { baseDir, resolveUrl, allowBareRelative = false }) {
+  if (/^(https?:)?\/\//.test(relPath) || relPath.startsWith('data:') || relPath.startsWith('blob:')) return null;
+  if (relPath.includes('?') || relPath.includes('#')) return null;
+  if (!/\.(js|mjs)$/.test(relPath)) return null;
+  let target;
+  if (relPath.startsWith('/')) target = resolveUrl(relPath);
+  else if (relPath.startsWith('.')) target = normalize(join(baseDir, relPath));
+  else if (allowBareRelative) target = normalize(join(baseDir, relPath));
+  else return null; // bare module specifier
+  if (!target) return null;
+  try {
+    const mtime = Math.floor(statSync(target).mtimeMs / 1000);
+    return `${relPath}?v=${mtime}`;
+  } catch {
+    return null;
+  }
+}
+
+export function rewriteJsImports(text, { baseDir, resolveUrl }) {
+  return text.replace(JS_IMPORT_RE, (whole, prefix, quote, path) => {
+    const v = versionedPath(path, { baseDir, resolveUrl });
+    return `${prefix}${quote}${v ?? path}${quote}`;
+  });
+}
+
+export function rewriteHtmlScripts(html, { baseDir, resolveUrl }) {
+  return html.replace(HTML_SCRIPT_RE, (whole, prefix, path, suffix) => {
+    const v = versionedPath(path, { baseDir, resolveUrl, allowBareRelative: true });
+    return `${prefix}${v ?? path}${suffix}`;
+  });
+}
+
+// For callers that need the base dir of a served file.
+export { dirname };

package/lib/inject.test.mjs

@@ -0,0 +1,87 @@
+// The dev server's HTML/JS transforms must mirror both the production
+// /g/<slug> serve path (head injection: GAME_SLUG + LOOOP_IDENTITY + platform
+// layer — see builder/functions/g/[[path]].ts) and the monorepo dev server
+// (?v=<mtime> cache-busting rewrites — see looop-core tools/game/dev_server.py).
+// A drift here means a game that works standalone but breaks published, or
+// vice versa.
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, writeFileSync, rmSync, utimesSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { injectHeadTags, rewriteHtmlScripts, rewriteJsImports, DEV_IDENTITY } from './inject.mjs';
+
+test('DEV_IDENTITY matches the serve path contract', () => {
+  // MUST match builder/functions/_shared/serve-identity.ts DEV_IDENTITY —
+  // games fail closed without a LOOOP_IDENTITY, and tests key off this user id.
+  assert.deepEqual(DEV_IDENTITY, { userId: 'dev-local-user', name: 'Dev', color: '#38bdf8' });
+});
+
+test('injects slug, identity, and platform module into <head>', () => {
+  const out = injectHeadTags('<html><head><title>x</title></head><body></body></html>', 'basket');
+  assert.match(out, /<head>\s*<script>window\.GAME_SLUG = "basket";<\/script>/);
+  assert.match(out, /window\.LOOOP_IDENTITY = \{"userId":"dev-local-user"/);
+  assert.match(
+    out,
+    /<script type="module">import \{ installPlatform \} from "\/shared\/platform\/platform\.js"; installPlatform\(\);<\/script>/,
+  );
+  // Identity must come as a classic script BEFORE the platform module so the
+  // global exists when any deferred module runs.
+  assert.ok(out.indexOf('LOOOP_IDENTITY') < out.indexOf('installPlatform'));
+});
+
+test('head injection escapes </script>-breaking values', () => {
+  const out = injectHeadTags('<head></head>', '</script><script>alert(1)');
+  assert.ok(!out.includes('</script><script>alert(1)'));
+  assert.match(out, /\\u003c\/script/);
+});
+
+test('injection without a <head> prepends', () => {
+  const out = injectHeadTags('<body>hi</body>', 'g');
+  assert.ok(out.startsWith('<script>window.GAME_SLUG'));
+});
+
+test('html <script src> gets ?v=<mtime>, absolute URLs and querystrings left alone', () => {
+  const dir = mkdtempSync(join(tmpdir(), 'looop-inject-'));
+  try {
+    writeFileSync(join(dir, 'main.js'), '// x');
+    utimesSync(join(dir, 'main.js'), new Date(1700000000000), new Date(1700000000000));
+    const html = '<script src="main.js"></script><script src="https://x.test/a.js"></script><script src="b.js?v=1"></script>';
+    const out = rewriteHtmlScripts(html, {
+      baseDir: dir,
+      resolveUrl: () => null,
+    });
+    assert.match(out, /src="main\.js\?v=1700000000"/);
+    assert.match(out, /src="https:\/\/x\.test\/a\.js"/);
+    assert.match(out, /src="b\.js\?v=1"/);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('js relative and absolute imports get ?v=<mtime>; bare specifiers untouched', () => {
+  const dir = mkdtempSync(join(tmpdir(), 'looop-inject-js-'));
+  try {
+    writeFileSync(join(dir, 'world.js'), '// w');
+    utimesSync(join(dir, 'world.js'), new Date(1700000000000), new Date(1700000000000));
+    const sharedDir = mkdtempSync(join(tmpdir(), 'looop-inject-shared-'));
+    writeFileSync(join(sharedDir, 'client.js'), '// c');
+    utimesSync(join(sharedDir, 'client.js'), new Date(1700000001000), new Date(1700000001000));
+    const src = [
+      "import './world.js';",
+      "import { x } from '/shared/ui/room/client.js';",
+      "import * as C from 'cannon-es';",
+      "const d = await import('./world.js');",
+    ].join('\n');
+    const out = rewriteJsImports(src, {
+      baseDir: dir,
+      resolveUrl: (p) => (p === '/shared/ui/room/client.js' ? join(sharedDir, 'client.js') : null),
+    });
+    assert.match(out, /'\.\/world\.js\?v=1700000000'/);
+    assert.match(out, /'\/shared\/ui\/room\/client\.js\?v=1700000001'/);
+    assert.match(out, /'cannon-es'/);
+    assert.match(out, /import\('\.\/world\.js\?v=1700000000'\)/);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});

package/lib/llm-shim.mjs

@@ -0,0 +1,74 @@
+// Local platform-services shim (:8788) — decision Q3b in cuqfzo.
+//
+// Thin auth/CORS plumbing between a game running on localhost and the
+// platform's services API (LLM today; whatever comes next). It forwards
+// /api/* and /lb* to the platform, attaching the creator's token as a Bearer
+// header. It is deliberately NOT a local implementation of any service and
+// never holds provider keys — those live only server-side.
+//
+// Port convention: :8788 canonically (shared/ui/llm/index.js derives
+// 8788 + (staticPort − 8000) from location.port — same rule dev.sh uses).
+import http from 'node:http';
+
+const FORWARD_PREFIXES = ['/api/', '/lb'];
+
+export const DEFAULT_API_BASE = 'https://play.looop.games';
+
+export function createLlmShim({ apiBase = DEFAULT_API_BASE, getToken = () => null } = {}) {
+  const server = http.createServer(async (req, res) => {
+    const urlPath = new URL(req.url, 'http://x').pathname;
+    if (!FORWARD_PREFIXES.some((p) => urlPath.startsWith(p))) {
+      res.writeHead(404, { 'Content-Type': 'text/plain' });
+      return res.end('404 — this shim only forwards /api/* and /lb*');
+    }
+    const cors = {
+      'Access-Control-Allow-Origin': '*',
+      'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE, OPTIONS',
+      'Access-Control-Allow-Headers': 'Content-Type, Authorization',
+    };
+    if (req.method === 'OPTIONS') {
+      res.writeHead(204, cors);
+      return res.end();
+    }
+    const chunks = [];
+    for await (const c of req) chunks.push(c);
+    const body = Buffer.concat(chunks);
+    const headers = { 'Content-Type': req.headers['content-type'] ?? 'application/json' };
+    const token = getToken();
+    if (token) headers.Authorization = `Bearer ${token}`;
+    try {
+      const upstream = await fetch(apiBase + req.url, {
+        method: req.method,
+        headers,
+        body: ['GET', 'HEAD'].includes(req.method) ? undefined : body,
+      });
+      const buf = Buffer.from(await upstream.arrayBuffer());
+      res.writeHead(upstream.status, {
+        ...cors,
+        'Content-Type': upstream.headers.get('content-type') ?? 'application/json',
+        'Content-Length': buf.length,
+      });
+      res.end(buf);
+    } catch (err) {
+      res.writeHead(502, { ...cors, 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ error: 'upstream unreachable', detail: String(err?.cause ?? err), apiBase }));
+    }
+  });
+
+  return {
+    server,
+    get port() {
+      return server.address()?.port;
+    },
+    listen(port, bind = '0.0.0.0') {
+      return new Promise((resolveP, rejectP) => {
+        server.once('error', rejectP);
+        server.listen(port, bind, () => resolveP(server.address().port));
+      });
+    },
+    close() {
+      server.close();
+      server.closeAllConnections?.();
+    },
+  };
+}

package/lib/llm-shim.test.mjs

@@ -0,0 +1,90 @@
+// The local services shim (:8788) is thin auth/CORS plumbing to the platform
+// API — NEVER a local implementation of a service and NEVER a holder of
+// provider keys (decision Q3b in cuqfzo). These tests run it against a mock
+// upstream and pin: path/method/body pass-through, the creator token becoming
+// an Authorization header, tokenless operation (pre-login dev must work), and
+// local CORS handling for the browser.
+import { test, after } from 'node:test';
+import assert from 'node:assert/strict';
+import http from 'node:http';
+import { createLlmShim } from './llm-shim.mjs';
+
+let lastReq = null;
+const upstream = http.createServer((req, res) => {
+  let body = '';
+  req.on('data', (c) => (body += c));
+  req.on('end', () => {
+    lastReq = { method: req.method, url: req.url, auth: req.headers.authorization ?? null, body };
+    res.writeHead(200, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ ok: true, echo: req.url }));
+  });
+});
+await new Promise((r) => upstream.listen(0, r));
+const apiBase = `http://localhost:${upstream.address().port}`;
+
+const shim = createLlmShim({ apiBase, getToken: () => 'looop_test_token' });
+await shim.listen(0);
+const base = `http://localhost:${shim.port}`;
+
+after(() => {
+  shim.close();
+  upstream.close();
+});
+
+test('forwards /api/llm with method, body, and bearer token', async () => {
+  const res = await fetch(`${base}/api/llm`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ prompt: 'hi' }),
+  });
+  assert.equal(res.status, 200);
+  assert.deepEqual(await res.json(), { ok: true, echo: '/api/llm' });
+  assert.equal(lastReq.method, 'POST');
+  assert.equal(lastReq.url, '/api/llm');
+  assert.equal(lastReq.auth, 'Bearer looop_test_token');
+  assert.equal(lastReq.body, '{"prompt":"hi"}');
+});
+
+test('forwards /lb paths too (leaderboards ride the same shim)', async () => {
+  const res = await fetch(`${base}/lb/pong/top`);
+  assert.equal(res.status, 200);
+  assert.equal(lastReq.url, '/lb/pong/top');
+});
+
+test('works without a token — no Authorization header sent', async () => {
+  const anon = createLlmShim({ apiBase, getToken: () => null });
+  await anon.listen(0);
+  try {
+    await fetch(`http://localhost:${anon.port}/api/llm`, { method: 'POST', body: '{}' });
+    assert.equal(lastReq.auth, null);
+  } finally {
+    anon.close();
+  }
+});
+
+test('answers preflight locally with permissive CORS', async () => {
+  const before = lastReq;
+  const res = await fetch(`${base}/api/llm`, {
+    method: 'OPTIONS',
+    headers: { Origin: 'http://localhost:8000', 'Access-Control-Request-Method': 'POST' },
+  });
+  assert.equal(res.status, 204);
+  assert.equal(res.headers.get('access-control-allow-origin'), '*');
+  assert.match(res.headers.get('access-control-allow-headers'), /content-type/i);
+  assert.equal(lastReq, before, 'preflight must not reach upstream');
+});
+
+test('non-API paths 404 instead of forwarding', async () => {
+  assert.equal((await fetch(`${base}/etc/passwd`)).status, 404);
+});
+
+test('upstream failure surfaces as 502, not a hang', async () => {
+  const dead = createLlmShim({ apiBase: 'http://127.0.0.1:1', getToken: () => null });
+  await dead.listen(0);
+  try {
+    const res = await fetch(`http://localhost:${dead.port}/api/llm`, { method: 'POST', body: '{}' });
+    assert.equal(res.status, 502);
+  } finally {
+    dead.close();
+  }
+});

package/lib/login.mjs

@@ -0,0 +1,90 @@
+// `looop login` — device-flow authentication (cuqfzo Slice 1, decisions
+// Q2/Q6, the `gh auth login` shape):
+//
+//   1. ask the platform for a pairing (device_code for us, user_code for the
+//      human),
+//   2. show the human the short code and open /activate in their browser,
+//   3. poll until they approve,
+//   4. store the minted creator token in ~/.looop/config.json.
+//
+// The secret never passes through the human's hands or the chat — non-dev
+// creators can't fumble a 40-char paste (why web-paste was rejected).
+import { spawn } from 'node:child_process';
+import { setToken, getToken, getApiBase } from './config.mjs';
+import { DEFAULT_API_BASE } from './llm-shim.mjs';
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+function defaultOpenBrowser(url) {
+  const [cmd, args] =
+    process.platform === 'darwin'
+      ? ['open', [url]]
+      : process.platform === 'win32'
+        ? ['cmd', ['/c', 'start', '', url]]
+        : ['xdg-open', [url]];
+  try {
+    spawn(cmd, args, { stdio: 'ignore', detached: true }).unref();
+  } catch {
+    // No browser available (headless) — the printed URL is the fallback.
+  }
+}
+
+async function postJson(url, body) {
+  const res = await fetch(url, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(body ?? {}),
+  });
+  return { status: res.status, body: await res.json().catch(() => ({})) };
+}
+
+export async function login({
+  apiBase = getApiBase(DEFAULT_API_BASE),
+  log = console.log,
+  openBrowser = defaultOpenBrowser,
+  pollIntervalMsOverride,
+} = {}) {
+  const { status, body: grant } = await postJson(`${apiBase}/api/device/code`);
+  if (status !== 200 || !grant.device_code) {
+    throw new Error(`could not start login against ${apiBase} (HTTP ${status})`);
+  }
+
+  log('');
+  log('  To connect this computer to your Looop account:');
+  log('');
+  log(`  1. Open   ${grant.verification_uri}`);
+  log(`  2. Enter  ${grant.user_code}`);
+  log('');
+  log('  (opening your browser…)');
+  openBrowser(grant.verification_uri_complete ?? grant.verification_uri);
+
+  const intervalMs = pollIntervalMsOverride ?? (grant.interval ?? 5) * 1000;
+  const deadline = Date.now() + (grant.expires_in ?? 900) * 1000;
+  while (Date.now() < deadline) {
+    await sleep(intervalMs);
+    const poll = await postJson(`${apiBase}/api/device/token`, { device_code: grant.device_code });
+    if (poll.status === 200 && poll.body.token) {
+      setToken(poll.body.token, { apiBase, userId: poll.body.user_id });
+      log('');
+      log(`  ✅ Logged in. This machine now builds and publishes as your account (${poll.body.user_id}).`);
+      return { userId: poll.body.user_id };
+    }
+    if (poll.body.error === 'authorization_pending') continue;
+    if (poll.body.error === 'expired_token') {
+      throw new Error('that login code expired before it was approved — run `looop login` again for a fresh one.');
+    }
+    throw new Error(`login failed: ${poll.body.error ?? `HTTP ${poll.status}`}`);
+  }
+  throw new Error('login timed out — run `looop login` again.');
+}
+
+export async function whoami({ apiBase = getApiBase(DEFAULT_API_BASE), log = console.log } = {}) {
+  const token = getToken();
+  if (!token) throw new Error('not logged in — run `looop login` first.');
+  const res = await fetch(`${apiBase}/api/me`, { headers: { Authorization: `Bearer ${token}` } });
+  if (res.status === 401) throw new Error('stored token was rejected (unauthenticated) — run `looop login` again.');
+  if (!res.ok) throw new Error(`whoami failed: HTTP ${res.status}`);
+  const me = await res.json();
+  log(`${me.name ?? me.userId}  (${me.userId})  via ${apiBase}`);
+  return me;
+}

package/lib/login.test.mjs

@@ -0,0 +1,89 @@
+// `looop login` — the CLI half of the device flow (cuqfzo Slice 1, Q6).
+// Driven against a mock platform implementing the real wire contract
+// (/api/device/code → poll /api/device/token → /api/me), pinning: the human
+// sees the code + URL, the CLI polls through authorization_pending, the token
+// lands in config (never printed), expiry fails cleanly.
+import { test, after } from 'node:test';
+import assert from 'node:assert/strict';
+import http from 'node:http';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { login, whoami } from './login.mjs';
+import { getToken, setToken } from './config.mjs';
+
+process.env.LOOOP_HOME = mkdtempSync(join(tmpdir(), 'looop-login-home-'));
+
+let pollsUntilApproved = 2;
+let expireEverything = false;
+const server = http.createServer(async (req, res) => {
+  const send = (status, body) => {
+    res.writeHead(status, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify(body));
+  };
+  if (req.url === '/api/device/code') {
+    return send(200, {
+      device_code: 'd'.repeat(64),
+      user_code: 'ABCD-EFGH',
+      verification_uri: 'http://mock/activate',
+      verification_uri_complete: 'http://mock/activate?code=ABCD-EFGH',
+      expires_in: 900,
+      interval: 5,
+    });
+  }
+  if (req.url === '/api/device/token') {
+    if (expireEverything) return send(400, { error: 'expired_token' });
+    if (pollsUntilApproved-- > 0) return send(400, { error: 'authorization_pending' });
+    return send(200, { token: `looop_${'e'.repeat(64)}`, user_id: 'u_fran' });
+  }
+  if (req.url === '/api/me') {
+    const ok = req.headers.authorization === `Bearer looop_${'e'.repeat(64)}`;
+    return ok ? send(200, { userId: 'u_fran', name: 'Fran', color: '#38bdf8' }) : send(401, { error: 'unauthenticated' });
+  }
+  send(404, { error: 'nope' });
+});
+await new Promise((r) => server.listen(0, r));
+const apiBase = `http://localhost:${server.address().port}`;
+
+after(() => {
+  server.close();
+  rmSync(process.env.LOOOP_HOME, { recursive: true, force: true });
+});
+
+test('login polls to a token, stores it, and never prints the secret', async () => {
+  const lines = [];
+  const opened = [];
+  const result = await login({
+    apiBase,
+    log: (s) => lines.push(s),
+    openBrowser: (url) => opened.push(url),
+    pollIntervalMsOverride: 10,
+  });
+  assert.equal(result.userId, 'u_fran');
+  assert.equal(getToken(), `looop_${'e'.repeat(64)}`);
+  const out = lines.join('\n');
+  assert.match(out, /ABCD-EFGH/);
+  assert.match(out, /http:\/\/mock\/activate/);
+  assert.ok(!out.includes('e'.repeat(64)), 'token leaked to output');
+  assert.deepEqual(opened, ['http://mock/activate?code=ABCD-EFGH']);
+});
+
+test('whoami reports the authenticated identity', async () => {
+  const lines = [];
+  const me = await whoami({ apiBase, log: (s) => lines.push(s) });
+  assert.equal(me.name, 'Fran');
+  assert.match(lines.join('\n'), /Fran/);
+});
+
+test('an expired code fails with a clear retry message', async () => {
+  expireEverything = true;
+  await assert.rejects(
+    () => login({ apiBase, log: () => {}, openBrowser: () => {}, pollIntervalMsOverride: 10 }),
+    /expired.*looop login/is,
+  );
+});
+
+test('whoami without a valid token says so', async () => {
+  setToken('looop_' + 'f'.repeat(64));
+  await assert.rejects(() => whoami({ apiBase, log: () => {} }), /not logged in|unauthenticated/i);
+});

package/lib/ports.mjs

@@ -0,0 +1,100 @@
+// Port conventions + takeover, mirroring looop-core tools/game/dev.sh.
+//
+// Canonical ports: static :8000, partykit :1999, services shim :8788. The
+// engine's browser clients derive the other two from location.port
+// (1999/8788 + (static − 8000)), so a non-default --port shifts all three
+// together and everything keeps lining up.
+//
+// Takeover: `looop dev` must "just work" — a stale dev session or orphaned
+// workerd holding a port means the user gets stale code with no recourse, so
+// we TERM (then KILL) the listener instead of skipping, exactly like dev.sh.
+import { execFileSync } from 'node:child_process';
+import net from 'node:net';
+import { networkInterfaces } from 'node:os';
+
+export const STATIC_PORT_BASE = 8000;
+export const MP_PORT_BASE = 1999;
+export const SHIM_PORT_BASE = 8788;
+
+export function portsFor(staticPort = STATIC_PORT_BASE) {
+  const offset = staticPort - STATIC_PORT_BASE;
+  return { static: staticPort, mp: MP_PORT_BASE + offset, shim: SHIM_PORT_BASE + offset };
+}
+
+export function portInUse(port) {
+  return new Promise((resolve) => {
+    const sock = net.connect({ port, host: '127.0.0.1' });
+    const done = (v) => {
+      sock.destroy();
+      resolve(v);
+    };
+    sock.setTimeout(300, () => done(false));
+    sock.on('connect', () => done(true));
+    sock.on('error', () => done(false));
+  });
+}
+
+function findPids(port) {
+  const pids = new Set();
+  try {
+    if (process.platform === 'win32') {
+      const out = execFileSync('netstat', ['-ano'], { encoding: 'utf8', timeout: 5000 });
+      const re = new RegExp(String.raw`\s\S+:${port}\s+\S+\s+LISTENING\s+(\d+)`, 'i');
+      for (const line of out.split('\n')) {
+        const m = re.exec(line);
+        if (m) pids.add(Number(m[1]));
+      }
+    } else {
+      const out = execFileSync('lsof', ['-ti', `:${port}`, '-sTCP:LISTEN'], {
+        encoding: 'utf8',
+        timeout: 5000,
+      });
+      for (const line of out.split('\n')) if (/^\d+$/.test(line.trim())) pids.add(Number(line.trim()));
+    }
+  } catch {
+    // lsof exits 1 when nothing listens — that's "no pids".
+  }
+  return pids;
+}
+
+function killPid(pid, force) {
+  try {
+    if (process.platform === 'win32') {
+      execFileSync('taskkill', [...(force ? ['/F'] : []), '/PID', String(pid)], { timeout: 5000 });
+    } else {
+      process.kill(pid, force ? 'SIGKILL' : 'SIGTERM');
+    }
+  } catch {
+    // Already gone.
+  }
+}
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+export async function killPort(port) {
+  let pids = findPids(port);
+  if (!pids.size) return true;
+  for (const p of pids) killPid(p, false);
+  for (let i = 0; i < 10; i++) {
+    await sleep(200);
+    if (!findPids(port).size) return true;
+  }
+  for (const p of findPids(port)) killPid(p, true);
+  for (let i = 0; i < 10; i++) {
+    await sleep(200);
+    if (!findPids(port).size) return true;
+  }
+  return false;
+}
+
+export function lanIp() {
+  // First non-internal private IPv4 — the address a phone on the same wifi
+  // uses to reach this machine. Null when offline / no private interface.
+  for (const addrs of Object.values(networkInterfaces())) {
+    for (const a of addrs ?? []) {
+      if (a.family !== 'IPv4' || a.internal) continue;
+      if (/^(192\.168\.|10\.|172\.(1[6-9]|2\d|3[01])\.)/.test(a.address)) return a.address;
+    }
+  }
+  return null;
+}

package/lib/project.mjs

@@ -0,0 +1,52 @@
+// Locate the standalone game project and its installed engine bundle.
+//
+// A project is the folder holding the game's package.json (created by
+// `looop create`, or by hand). The slug — the published URL is
+// play.looop.games/g/<slug> — defaults to the folder name; package.json's
+// `looop.slug` overrides it for folks whose repo name differs.
+import { existsSync, readFileSync } from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
+
+export function findProject(startDir = process.cwd()) {
+  let dir = resolve(startDir);
+  for (;;) {
+    const pkgPath = join(dir, 'package.json');
+    if (existsSync(pkgPath) && existsSync(join(dir, 'index.html'))) {
+      let pkg = {};
+      try {
+        pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+      } catch {
+        // Unparseable package.json: still treat as the project root; slug
+        // falls back to the folder name.
+      }
+      return { dir, slug: pkg?.looop?.slug || basename(dir), pkg };
+    }
+    const parent = dirname(dir);
+    if (parent === dir) {
+      throw new Error(
+        `Not inside a Looop game project (no folder with both package.json and index.html above ${startDir}). ` +
+          'Run this from your game folder, or bootstrap one with `looop create <name>`.',
+      );
+    }
+    dir = parent;
+  }
+}
+
+export function resolveEngine(projectDir) {
+  const dir = join(projectDir, 'node_modules', '@looop-games', 'engine');
+  const pkgPath = join(dir, 'package.json');
+  if (!existsSync(pkgPath)) {
+    throw new Error(
+      'the Looop engine is not installed in this project.\n' +
+        `Expected it at ${dir}.\n` +
+        'Run `looop dev` (or `looop publish`) — it downloads the engine from the platform (sign-in required).',
+    );
+  }
+  const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+  return {
+    dir,
+    version: pkg.version,
+    sharedDir: join(dir, 'shared'),
+    roomServerDir: join(dir, 'room-server'),
+  };
+}