@homie-rocks/studio 0.2.0 → 0.3.0

package/README.md

@@ -10,7 +10,7 @@ Most people never run this by hand: the Homie plugin for Claude Code and Codex d
 and the person approves Cloudflare once in their browser.
 
 ```sh
-npx -y --package=https://homie.rocks/npm/homie-studio-0.2.0.tgz homie-studio new ./night-owls --name "Night Owls"
+npx -y --package=https://homie.rocks/npm/homie-studio-0.3.0.tgz homie-studio new ./night-owls --name "Night Owls"
 cd night-owls && npm install
 npx homie-studio game new crown-thief --from gem-rush --name "Crown Thief"
 npx homie-studio dev                                   # the whole site locally
@@ -19,6 +19,15 @@ npx homie-studio deploy                                # the studio's own Cloudf
 npx homie-studio publish                               # the homie.rocks directory
 ```
 
+An existing single-player web game becomes a multiplayer one with the port toolkit
+(the plugin's `port` skill drives it):
+
+```sh
+npx homie-studio port plan ../my-game                  # grade it: easy, medium, hard or not a fit, and why
+npx homie-studio port import ../my-game --id my-game   # bring it into games/ (static, bundle or its own build)
+npx homie-studio port check my-game --url http://127.0.0.1:8787   # the owner tests, real touch, host kill, late joiner, a round
+```
+
 | Path | What it is |
 | --- | --- |
 | `bin/homie-studio.mjs` | The CLI. |
@@ -26,7 +35,10 @@ npx homie-studio publish                               # the homie.rocks directo
 | `lib/build.mjs` | `build`: games bundled with esbuild into `site/dist`, `games.json`, each game's shared `source.json`. |
 | `lib/cloudflare.mjs` | `deploy`: Wrangler, D1, R2, migrations, the directory claim; refuses resources it did not create. |
 | `lib/check.mjs` | `check`: two fresh Chrome processes (computer + phone) must share a room and finish a round. |
-| `worker/index.mjs` | The site Worker and the `Table` (netplay relay, `room.mjs`) and `Lobby` Durable Objects. |
+| `lib/port.mjs` | `port plan` (reads a game and grades the port) and `port import`. |
+| `lib/port-check.mjs` | `port check`: held and alternating directions on keys, Android Chrome and iPhone WebKit touch, UI cover, two browsers finishing a round, a killed host, a late joiner, the big screen. |
+| `port/` | The port toolkit (`@homie-rocks/studio/port`, or `window.HomiePort` from `homie-port.js` in a static game): `createRoom`, the touch kit, keys, camera rules, bots, a HUD, sandbox shims, first-touch audio, `exposePort`. |
+| `worker/index.mjs` | The site Worker and the `Table` (netplay relay, `room.mjs`) and `Lobby` Durable Objects; `/<game>/tv` is the big screen with a join QR (`qr.mjs`). |
 | `netplay/` | The netplay contract (`NETPLAY.md`) and its game helper (`@homie-rocks/studio/netplay`). |
 | `starters/gem-rush/` | The reference multiplayer starter. |
 

package/bin/homie-studio.mjs

@@ -11,6 +11,9 @@
  *   homie-studio build [<id>]
  *   homie-studio dev [--port 8787]
  *   homie-studio check <id> [--url <site>] [--shots <dir>]
+ *   homie-studio port plan <game folder>
+ *   homie-studio port import <game folder> --id <id> [--name "<Name>"] [--mode static|bundle|command]
+ *   homie-studio port check <id> [--url <site>] [--only owner-desk,owner-phone,owner-iphone,round,life,tv] [--shots <dir>]
  *   homie-studio deploy
  *   homie-studio publish
  *   homie-studio media put <file> [--as <key>]
@@ -25,19 +28,22 @@ import { build } from '../lib/build.mjs';
 import { check } from '../lib/check.mjs';
 import { deploy, whoami, wranglerBin } from '../lib/cloudflare.mjs';
 import { publish } from '../lib/directory.mjs';
+import { importPort, planPort } from '../lib/port.mjs';
+import { portCheck } from '../lib/port-check.mjs';
 import { newStudio } from '../lib/scaffold.mjs';
 import { listGames, newGame, readStudio, remixGame, requireStudio, starters, writeStudio } from '../lib/studio.mjs';
 import { STUDIO_VERSION } from '../lib/version.mjs';
 
 const argv = process.argv.slice(2);
 const flags = new Map();
+const BOOL_FLAGS = ['json', 'yes', 'detach', 'no-install'];
 const positional = [];
 for (let i = 0; i < argv.length; i++) {
   const a = argv[i];
   if (a.startsWith('--')) {
     const [k, v] = a.slice(2).split(/=(.*)/s, 2);
     if (v !== undefined) flags.set(k, v);
-    else if (argv[i + 1] !== undefined && !argv[i + 1].startsWith('--') && !['json', 'yes', 'detach', 'no-install'].includes(k)) flags.set(k, argv[++i]);
+    else if (argv[i + 1] !== undefined && !argv[i + 1].startsWith('--') && !BOOL_FLAGS.includes(k)) flags.set(k, argv[++i]);
     else flags.set(k, true);
   } else positional.push(a);
 }
@@ -46,7 +52,8 @@ const log = asJson ? () => {} : (line) => process.stderr.write(`${line}\n`);
 
 function print(result) {
   if (asJson) { process.stdout.write(`${JSON.stringify(result, null, 2)}\n`); return; }
-  if (result.ok === false) { process.stdout.write(`homie-studio: ${result.why ?? 'failed'}\n`); return; }
+  if (result.ok === false && result.command !== 'port check') { process.stdout.write(`homie-studio: ${result.why ?? 'failed'}\n`); return; }
+  if (result.ok === false && result.command === 'port check' && !result.rows) { process.stdout.write(`homie-studio: ${result.why ?? 'failed'}\n`); return; }
   const lines = [];
   switch (result.command) {
     case 'new':
@@ -68,6 +75,22 @@ function print(result) {
     case 'publish':
       lines.push(`Listed in the directory: ${result.studioPage ?? result.directory}`, ...(result.games ?? []).map((g) => `  ${g.name}: ${g.play}`));
       break;
+    case 'port plan': {
+      const f = result.facts;
+      lines.push(`Port plan for ${result.folder}`, '', `Difficulty: ${result.grade.toUpperCase()}`, ...result.reasons.map((r) => `  - ${r}`), '',
+        `What it is: ${f.engine.join(', ')}; ${f.loc} lines of game code in ${f.files} files (${Math.round(f.bytes / 1024)} KB); ${f.turnBased ? 'turn-based / moves on input' : 'real time'}${f.physics.length ? `; physics: ${f.physics.join(', ')}` : ''}.`,
+        `Input: keys ${f.input.keys}, mouse ${f.input.mouse}, touch ${f.input.touch}, pointer ${f.input.pointer}${f.input.pointerLock ? ', pointer lock' : ''}.`,
+        `Recommended: movement "${result.recommend.movement}", check view "${result.recommend.view}", build "${result.recommend.build}".`,
+        `Licence: ${result.licence.kind}${result.licence.file ? ` (${result.licence.file})` : ''}.`, '', 'Risks:', ...(result.risks.length ? result.risks.map((r) => `  - ${r}`) : ['  - none found by reading; the checks will say']));
+      break;
+    }
+    case 'port import':
+      lines.push(`games/${result.id} is a port of ${result.from} (${result.files} files, build "${result.mode}", draft grade ${result.plan.grade}).`, ...result.edits.map((e) => `  ${e}`), '', 'Next:', ...result.next.map((n) => `  - ${n}`));
+      break;
+    case 'port check':
+      lines.push(`${result.ok ? 'PASS' : 'NOT YET'}: ${result.game} at ${result.url} (${Math.round(result.totalMs / 1000)} s)`,
+        ...result.passed.map((p) => `  ok    ${p}`), ...result.failed.map((f) => `  FAIL  ${f}`), ...result.skipped.map((f) => `  skip  ${f}`), '', `Receipt and screenshots: ${result.out}`);
+      break;
     case 'check':
       lines.push(`PASS: two fresh browsers in room ${result.room} finished round ${result.round.n} (${result.round.humans} humans, ${result.round.bots} bots) in ${Math.round(result.totalMs / 1000)} s.`,
         ...result.seats.map((s) => `  ${s.browser}: seat ${s.seat} (${s.role}), seated in ${(s.seatedMs / 1000).toFixed(1)} s`));
@@ -89,7 +112,15 @@ async function main() {
   if (cmd === 'new') return newStudio(positional[1], { name: flags.get('name'), homie: flags.get('homie'), slug: flags.get('slug'), install: !flags.has('no-install') });
   if (cmd === 'starters') return { ok: true, command: 'starters', starters: starters() };
 
+  if (cmd === 'port' && sub === 'plan') return planPort(positional[2] ?? '.');
   const root = requireStudio();
+  if (cmd === 'port' && sub === 'import') return importPort(root, positional[2], flags.get('id'), { name: flags.get('name'), mode: flags.get('mode') });
+  if (cmd === 'port' && sub === 'check') {
+    const game = positional[2] ?? listGames(root)[0]?.id;
+    const url = flags.get('url') ?? readStudio(root).cloudflare?.url;
+    if (!url) return { ok: false, command: 'port check', why: 'give --url (the local dev address or the live site)' };
+    return portCheck({ url, game, root, only: flags.get('only') ?? null, shots: flags.get('shots') ? resolve(flags.get('shots')) : null, log });
+  }
   if (cmd === 'game' && sub === 'new') return newGame(root, positional[2], { from: flags.get('from') ?? 'gem-rush', name: flags.get('name') });
   if (cmd === 'game' && sub === 'remix') return remixGame(root, positional[2], flags.get('id'), { name: flags.get('name') });
   if (cmd === 'games') return { ok: true, command: 'games', games: listGames(root).map(({ dir, ...g }) => ({ ...g, dir: relative(root, dir) })) };
@@ -159,7 +190,7 @@ try {
   if (result && result.command !== 'help') print(result);
   if (result?.ok === false) process.exitCode = 1;
   // Chrome's pipes can outlive browser.close(); a finished check must not hang its caller.
-  if (result?.command === 'check') process.exit(process.exitCode ?? 0);
+  if (result?.command === 'check' || result?.command === 'port check') process.exit(process.exitCode ?? 0);
 } catch (error) {
   print({ ok: false, why: error instanceof Error ? error.message : String(error) });
   process.exitCode = 1;

package/lib/build.mjs

@@ -6,14 +6,51 @@
  *   site/dist/games/<id>/assets/main.js    its bundle (esbuild; @homie-rocks/studio/netplay inlined)
  *   site/dist/games/<id>/...               everything in games/<id>/public/
  *   site/dist/games.json                   { studio, games[] } from studio.json and game.json files
+ *
+ * game.json "build" picks how a game becomes files (a ported game keeps its own shape):
+ *   (absent) / { "mode": "bundle" }   src/main.ts (or "entry") bundled by esbuild — new games and ES-module ports
+ *   { "mode": "static" }              the folder copied as it is (plain <script> games), plus homie-port.js,
+ *                                     the port toolkit as one classic script (window.HomiePort); an "entry"
+ *                                     is bundled to assets/main.js as well
+ *   { "mode": "command", "command": "npm run build", "out": "dist" }
+ *                                     the game's own build (Vite, webpack…), then its output copied; base must be './'
  */
+import { spawnSync } from 'node:child_process';
 import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { createRequire } from 'node:module';
-import { join } from 'node:path';
-import { listGames, readStudio } from './studio.mjs';
+import { join, relative } from 'node:path';
+import { PACKAGE_ROOT, listGames, readStudio } from './studio.mjs';
 import { STUDIO_VERSION } from './version.mjs';
 
-const SOURCE_SKIP = new Set(['node_modules', 'dist', '.git', '.wrangler']);
+const SOURCE_SKIP = new Set(['node_modules', 'dist', '.git', '.wrangler', '.port']);
+/** Never copied into a static game's served folder. */
+const STATIC_SKIP = new Set(['node_modules', '.git', '.wrangler', '.port', '.DS_Store', 'game.json', 'PORT.md']);
+const LOADERS = { '.png': 'file', '.jpg': 'file', '.jpeg': 'file', '.gif': 'file', '.webp': 'file', '.mp3': 'file', '.ogg': 'file', '.wav': 'file', '.m4a': 'file', '.glb': 'file', '.gltf': 'file', '.bin': 'file', '.hdr': 'file', '.svg': 'file', '.json': 'json', '.woff2': 'file', '.ttf': 'file' };
+
+/** The port toolkit as one classic script (window.HomiePort), for static games. Built once per build. */
+async function portScript(esbuild, root, cache) {
+  if (cache.text) return cache.text;
+  const entry = join(PACKAGE_ROOT, 'port', 'global.ts');
+  const res = await esbuild.build({ entryPoints: [entry], bundle: true, format: 'iife', target: 'es2020', minify: true, write: false, absWorkingDir: root, logLevel: 'silent' });
+  cache.text = `/* homie-port.js — @homie-rocks/studio port toolkit (window.HomiePort). Load it first in <head>. */\n${res.outputFiles[0].text}`;
+  return cache.text;
+}
+
+function copyStatic(from, to) {
+  for (const entry of readdirSync(from, { withFileTypes: true })) {
+    if (STATIC_SKIP.has(entry.name)) continue;
+    const src = join(from, entry.name);
+    const dest = join(to, entry.name);
+    if (entry.isDirectory()) { mkdirSync(dest, { recursive: true }); copyStatic(src, dest); }
+    else if (entry.isFile()) cpSync(src, dest);
+  }
+}
+
+function dirBytes(dir) {
+  let n = 0;
+  for (const e of readdirSync(dir, { withFileTypes: true })) n += e.isDirectory() ? dirBytes(join(dir, e.name)) : statSync(join(dir, e.name)).size;
+  return n;
+}
 const TEXT = /\.(ts|tsx|js|mjs|jsx|json|html|css|md|txt|svg|glsl|wgsl|frag|vert)$/i;
 /** Text files of a game folder, capped (2 MB total, 512 KB each): what `homie-studio game remix` takes. */
 export function sourceOf(dir, id) {
@@ -47,31 +84,55 @@ export async function build(root, { only = null, log = () => {} } = {}) {
   if (!only) rmSync(dist, { recursive: true, force: true });
   mkdirSync(dist, { recursive: true });
   const built = [];
+  const cache = {};
   for (const g of games) {
     const out = join(dist, 'games', g.id);
     rmSync(out, { recursive: true, force: true });
     mkdirSync(join(out, 'assets'), { recursive: true });
-    const entry = join(g.dir, g.entry ?? 'src/main.ts');
-    if (!existsSync(entry)) throw new Error(`games/${g.id}: entry ${g.entry ?? 'src/main.ts'} not found`);
+    const mode = g.build?.mode ?? 'bundle';
     const started = Date.now();
-    const result = await esbuild.build({
-      entryPoints: [entry], bundle: true, format: 'esm', target: 'es2022', minify: true, sourcemap: false,
-      outfile: join(out, 'assets', 'main.js'), absWorkingDir: root, logLevel: 'silent', metafile: true,
-      loader: { '.png': 'file', '.jpg': 'file', '.webp': 'file', '.mp3': 'file', '.ogg': 'file', '.wav': 'file', '.glb': 'file', '.svg': 'file' },
-      assetNames: '[name]-[hash]',
-    }).catch((error) => {
-      const first = error.errors?.[0];
-      throw new Error(`games/${g.id} did not build: ${first ? `${first.text}${first.location ? ` (${first.location.file}:${first.location.line})` : ''}` : error.message}`);
-    });
-    const html = join(g.dir, 'index.html');
-    if (!existsSync(html)) throw new Error(`games/${g.id}/index.html is missing`);
-    writeFileSync(join(out, 'index.html'), readFileSync(html, 'utf8'));
-    if (existsSync(join(g.dir, 'public'))) cpSync(join(g.dir, 'public'), out, { recursive: true });
+    let warnings = 0;
+    const bundle = async (entryRel) => {
+      const entry = join(g.dir, entryRel);
+      if (!existsSync(entry)) throw new Error(`games/${g.id}: entry ${entryRel} not found`);
+      const result = await esbuild.build({
+        entryPoints: [entry], bundle: true, format: 'esm', target: 'es2022', minify: true, sourcemap: false,
+        outfile: join(out, 'assets', 'main.js'), absWorkingDir: root, logLevel: 'silent', metafile: true,
+        loader: LOADERS, assetNames: '[name]-[hash]',
+      }).catch((error) => {
+        const first = error.errors?.[0];
+        throw new Error(`games/${g.id} did not build: ${first ? `${first.text}${first.location ? ` (${first.location.file}:${first.location.line})` : ''}` : error.message}`);
+      });
+      warnings += result.warnings.length;
+    };
+    if (mode === 'static') {
+      copyStatic(g.dir, out);
+      writeFileSync(join(out, 'homie-port.js'), await portScript(esbuild, root, cache));
+      if (g.entry) await bundle(g.entry);
+      const html = readFileSync(join(out, 'index.html'), 'utf8');
+      if (!/homie-port\.js/.test(html)) log(`warning: games/${g.id}/index.html does not load ./homie-port.js (the port toolkit); add <script src="./homie-port.js"></script> first in <head>`);
+    } else if (mode === 'command') {
+      const command = String(g.build.command ?? 'npm run build');
+      const res = spawnSync(command, { cwd: g.dir, shell: true, encoding: 'utf8', timeout: 10 * 60_000, maxBuffer: 64 * 1024 * 1024 });
+      if (res.status !== 0) throw new Error(`games/${g.id}: \`${command}\` failed: ${`${res.stdout ?? ''}${res.stderr ?? ''}`.trim().split('\n').slice(-6).join(' ')}`);
+      const built = join(g.dir, String(g.build.out ?? 'dist'));
+      if (!existsSync(join(built, 'index.html'))) throw new Error(`games/${g.id}: \`${command}\` left no index.html in ${relative(g.dir, built) || '.'}`);
+      cpSync(built, out, { recursive: true });
+      writeFileSync(join(out, 'homie-port.js'), await portScript(esbuild, root, cache));
+    } else {
+      await bundle(g.entry ?? 'src/main.ts');
+      const html = join(g.dir, 'index.html');
+      if (!existsSync(html)) throw new Error(`games/${g.id}/index.html is missing`);
+      writeFileSync(join(out, 'index.html'), readFileSync(html, 'utf8'));
+    }
+    if (mode !== 'static' && existsSync(join(g.dir, 'public'))) cpSync(join(g.dir, 'public'), out, { recursive: true });
+    if (!existsSync(join(out, 'index.html'))) throw new Error(`games/${g.id}/index.html is missing`);
     // The game's own source, for other studios to remix (game.json "share": { "source": false } keeps it private).
     if (g.share?.source !== false) writeFileSync(join(out, 'source.json'), `${JSON.stringify(sourceOf(g.dir, g.id))}\n`);
-    const bytes = statSync(join(out, 'assets', 'main.js')).size;
-    built.push({ id: g.id, name: g.name, bytes, ms: Date.now() - started, warnings: result.warnings.length });
-    log(`built ${g.id} (${Math.round(bytes / 1024)} KB)`);
+    const main = join(out, 'assets', 'main.js');
+    const bytes = existsSync(main) ? statSync(main).size : dirBytes(out);
+    built.push({ id: g.id, name: g.name, mode, bytes, ms: Date.now() - started, warnings });
+    log(`built ${g.id} (${mode}, ${Math.round(bytes / 1024)} KB)`);
   }
   const all = listGames(root);
   const catalogue = {
@@ -79,6 +140,7 @@ export async function build(root, { only = null, log = () => {} } = {}) {
     games: all.filter((g) => existsSync(join(dist, 'games', g.id, 'index.html'))).map((g) => ({
       id: g.id, name: g.name ?? g.id, blurb: g.blurb ?? '', players: g.players ?? { min: 1, max: 8 },
       roundSeconds: g.roundSeconds ?? null, movement: g.netplay?.movement ?? null, cover: g.cover ?? null,
+      ...(g.screen ? { screen: g.screen } : {}),
     })),
   };
   writeFileSync(join(dist, 'games.json'), `${JSON.stringify(catalogue, null, 2)}\n`);