@homie-rocks/studio 0.2.0

package/lib/cloudflare.mjs

@@ -0,0 +1,155 @@
+/**
+ * `homie-studio deploy` — the studio's site on the studio's OWN Cloudflare
+ * account, through Cloudflare's own tool (Wrangler, pinned in the studio).
+ *
+ * The person's only step is Wrangler's sign-in (`npx wrangler login`, one
+ * approval in their browser); Wrangler keeps that login, this never sees a key.
+ *
+ * It creates what the studio needs, by the names in studio.json:
+ *   the Worker (pages + rooms), a D1 database, an R2 bucket (when the account
+ *   has R2), the Table/Lobby Durable Objects (declared by the Worker)
+ * and it REFUSES to touch a Worker, database or bucket of that name that this
+ * studio did not create (studio.json `cloudflare.created` is the record), so it
+ * can never overwrite someone's existing site.
+ */
+import { spawnSync } from 'node:child_process';
+import { existsSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { build } from './build.mjs';
+import { wranglerConfig } from './scaffold.mjs';
+import { readStudio, writeStudio } from './studio.mjs';
+
+const ANSI = /\u001b\[[0-9;]*m/g;
+
+export function wranglerBin(root) {
+  const local = join(root, 'node_modules', '.bin', 'wrangler');
+  return existsSync(local) ? local : null;
+}
+
+function runner(root, env) {
+  const bin = wranglerBin(root);
+  if (!bin) throw new Error('Wrangler is not installed in this studio yet: run `npm install` in the studio folder first');
+  return (args, { cwd = join(root, 'site'), input } = {}) => {
+    const res = spawnSync(bin, args, {
+      cwd, env: { ...process.env, ...env, WRANGLER_SEND_METRICS: 'false', CI: '1' }, encoding: 'utf8',
+      input, maxBuffer: 64 * 1024 * 1024, timeout: 10 * 60_000,
+    });
+    const out = `${res.stdout ?? ''}${res.stderr ?? ''}`.replace(ANSI, '');
+    return { code: res.status ?? 1, out, stdout: (res.stdout ?? '').replace(ANSI, '') };
+  };
+}
+
+/** Who Wrangler is signed in as, or null. Never prints a token. */
+export function whoami(root, env = {}) {
+  const w = runner(root, env);
+  const res = w(['whoami', '--json'], { cwd: root });
+  if (res.code !== 0) return null;
+  try { const d = JSON.parse(res.stdout); return d.loggedIn ? { accounts: (d.accounts ?? []).map((a) => ({ id: a.id, name: a.name })), authType: d.authType } : null; } catch { return null; }
+}
+
+function parseJson(text) {
+  const start = text.search(/[[{]/);
+  if (start < 0) return null;
+  try { return JSON.parse(text.slice(start)); } catch { return null; }
+}
+
+export async function deploy(root, { log = () => {}, homie } = {}) {
+  const studio = readStudio(root);
+  const cf = { r2: `${studio.slug}-media`, created: [], ...studio.cloudflare };
+  const created = new Set(cf.created ?? []);
+  const who = whoami(root);
+  if (!who) {
+    return { ok: false, command: 'deploy', needs: 'cloudflare-login', why: 'Wrangler is not signed in to Cloudflare. Run `npx wrangler login` in the studio folder: it opens Cloudflare in the browser and the person approves once. Then run `npm run deploy` again.' };
+  }
+  const accountId = process.env.CLOUDFLARE_ACCOUNT_ID || cf.accountId || (who.accounts.length === 1 ? who.accounts[0].id : null);
+  if (!accountId) {
+    return { ok: false, command: 'deploy', needs: 'cloudflare-account', why: `This Cloudflare login can reach ${who.accounts.length} accounts; ask the person which one this studio uses and put its id in studio.json (cloudflare.accountId).`, accounts: who.accounts };
+  }
+  const w = runner(root, { CLOUDFLARE_ACCOUNT_ID: accountId });
+  // Record every resource the moment it exists, so a deploy cut short (an expired login, a network drop) resumes
+  // instead of refusing its own database as "someone else's" next time.
+  const remember = (key) => {
+    created.add(key);
+    writeStudio(root, { ...readStudio(root), cloudflare: { ...readStudio(root).cloudflare, accountId, created: [...created].sort() } });
+  };
+  const steps = [];
+  const step = (what, extra = {}) => { steps.push({ what, ...extra }); log(what); };
+
+  const b = await build(root, { log });
+  if (!b.catalogue.length) return { ok: false, command: 'deploy', why: 'no games built yet: make one with `npx --no-install homie-studio game new <id> --from gem-rush`' };
+  step(`built ${b.catalogue.length} game(s)`);
+
+  // The Worker: never one this studio did not make.
+  if (!created.has(`worker:${cf.worker}`)) {
+    const exists = w(['versions', 'list', '--name', cf.worker, '--json']);
+    if (exists.code === 0) {
+      return { ok: false, command: 'deploy', why: `A Worker named "${cf.worker}" already exists on this Cloudflare account and this studio did not create it, so nothing was deployed. Pick another name in studio.json (cloudflare.worker) and site/wrangler.jsonc (name).` };
+    }
+    if (!/10007|does not exist/i.test(exists.out)) return { ok: false, command: 'deploy', why: `could not check the Worker name: ${exists.out.trim().split('\n').slice(-3).join(' ')}` };
+  }
+
+  // D1.
+  const list = w(['d1', 'list', '--json']);
+  const dbs = parseJson(list.out) ?? [];
+  let db = dbs.find((d) => d.name === cf.d1);
+  if (db && !created.has(`d1:${cf.d1}`)) {
+    return { ok: false, command: 'deploy', why: `A D1 database named "${cf.d1}" already exists on this account and this studio did not create it; nothing was deployed. Pick another name in studio.json (cloudflare.d1).` };
+  }
+  if (!db) {
+    const made = w(['d1', 'create', cf.d1]);
+    const id = /"?database_id"?\s*[:=]\s*"([0-9a-f-]{36})"/.exec(made.out)?.[1];
+    if (made.code !== 0 || !id) return { ok: false, command: 'deploy', why: `could not create the D1 database "${cf.d1}": ${made.out.trim().split('\n').slice(-4).join(' ')}` };
+    db = { name: cf.d1, uuid: id };
+    remember(`d1:${cf.d1}`);
+    step(`created D1 ${cf.d1}`);
+  }
+
+  // R2, when the account has it (R2 needs a payment method on the account; without it the site runs without MEDIA).
+  let r2 = cf.r2 || null;
+  if (r2 && !created.has(`r2:${r2}`)) {
+    const buckets = w(['r2', 'bucket', 'list']);
+    const names = [...buckets.out.matchAll(/^name:\s+(\S+)/gm)].map((m) => m[1]);
+    if (names.includes(r2)) {
+      return { ok: false, command: 'deploy', why: `An R2 bucket named "${r2}" already exists on this account and this studio did not create it; nothing was deployed. Pick another name in studio.json (cloudflare.r2).` };
+    }
+    const made = w(['r2', 'bucket', 'create', r2]);
+    if (made.code === 0) { remember(`r2:${r2}`); step(`created R2 ${r2}`); }
+    else if (/enable R2|R2 is not enabled|10042|purchase|subscription/i.test(made.out)) { step('R2 is not enabled on this account: the site deploys without media storage for now'); r2 = null; }
+    else return { ok: false, command: 'deploy', why: `could not create the R2 bucket "${r2}": ${made.out.trim().split('\n').slice(-4).join(' ')}` };
+  }
+
+  writeFileSync(join(root, 'site', 'wrangler.jsonc'), wranglerConfig({ worker: cf.worker, name: studio.name, d1: cf.d1, d1Id: db.uuid, r2 }));
+  const migrate = w(['d1', 'migrations', 'apply', cf.d1, '--remote']);
+  if (migrate.code !== 0) return { ok: false, command: 'deploy', why: `D1 migrations failed: ${migrate.out.trim().split('\n').slice(-4).join(' ')}` };
+  step('D1 migrations applied');
+
+  const started = Date.now();
+  const dep = w(['deploy']);
+  if (dep.code !== 0) return { ok: false, command: 'deploy', why: `wrangler deploy failed: ${dep.out.trim().split('\n').slice(-6).join(' ')}` };
+  remember(`worker:${cf.worker}`);
+  const url = /https:\/\/[a-z0-9.-]+\.workers\.dev/i.exec(dep.out)?.[0] ?? cf.url ?? null;
+  step(`deployed ${cf.worker} in ${Math.round((Date.now() - started) / 1000)} s`, { url });
+
+  // The homie.rocks directory claim: the site serves it, which proves this studio controls the site.
+  const directory = homie || studio.homie?.directory || 'https://homie.rocks';
+  let claim = null;
+  if (url) {
+    try {
+      const res = await fetch(`${directory.replace(/\/+$/, '')}/api/studio/claim?site=${encodeURIComponent(url)}`);
+      const body = await res.json();
+      if (res.ok && /^[a-f0-9]{16,128}$/.test(body.claim ?? '')) claim = body.claim;
+    } catch { /* the directory is optional for a live site */ }
+    if (claim) {
+      const put = w(['d1', 'execute', cf.d1, '--remote', '--command', `INSERT OR REPLACE INTO meta (key, value) VALUES ('homie_claim', '${claim}')`]);
+      step(put.code === 0 ? 'directory claim stored' : 'could not store the directory claim (publish will say so)');
+    }
+  }
+
+  const next = { ...cf, accountId, url, d1Id: db.uuid, r2, created: [...created].sort(), deployedAt: new Date().toISOString() };
+  writeStudio(root, { ...studio, cloudflare: next });
+  return {
+    ok: true, command: 'deploy', url, worker: cf.worker, d1: cf.d1, r2, account: accountId, steps,
+    games: b.catalogue.map((id) => ({ id, page: url ? `${url}/${id}/` : null, play: url ? `${url}/${id}/play` : null })),
+    claim: Boolean(claim), directory,
+  };
+}

package/lib/directory.mjs

@@ -0,0 +1,19 @@
+/**
+ * The homie.rocks directory, from a studio's side. The directory lists games;
+ * it never hosts them. A studio proves it controls its site by serving the
+ * claim the directory gave it (`homie-studio deploy` stores it in D1), so
+ * nobody can list games under someone else's site.
+ */
+import { readStudio } from './studio.mjs';
+
+export async function publish(root, { homie, site } = {}) {
+  const studio = readStudio(root);
+  const directory = (homie || studio.homie?.directory || 'https://homie.rocks').replace(/\/+$/, '');
+  const url = site || studio.cloudflare?.url;
+  if (!url) return { ok: false, command: 'publish', why: 'this studio has no live site yet: run `npm run deploy` first' };
+  const res = await fetch(`${directory}/api/studio/publish`, {
+    method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ site: url }),
+  }).catch((error) => ({ ok: false, status: 0, json: async () => ({ error: String(error.message) }) }));
+  const body = await res.json().catch(() => ({}));
+  return { ok: Boolean(res.ok && body.ok), command: 'publish', directory, site: url, ...body };
+}

package/lib/scaffold.mjs

@@ -0,0 +1,254 @@
+/**
+ * `homie-studio new <folder> --name "<Studio Name>"` — a studio is ONE
+ * monorepo: a visible folder the person opens in Claude or Codex.
+ *
+ *   AGENTS.md            what this studio is and how to work in it (both apps)
+ *   CLAUDE.md            imports AGENTS.md (Claude Code's documented way to share it)
+ *   studio.json          the studio's name, slug, and its Cloudflare resources
+ *   package.json         @homie-rocks/studio and wrangler, pinned
+ *   games/<id>/          one folder per game (game.json, index.html, src/)
+ *   music/ videos/       manifests in the repo; the big files live in the studio's R2
+ *   posts/               words the studio publishes
+ *   site/                the studio's Worker (pages, rooms), its D1 migrations
+ *   .claude/skills/      skills only this studio uses
+ *
+ * It writes only into a folder that is new or empty, never guesses one, and
+ * lists every file it writes, so the person sees exactly what changed.
+ */
+import { execFileSync } from 'node:child_process';
+import { existsSync, mkdirSync, readdirSync, realpathSync, statSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, relative, resolve } from 'node:path';
+import { STUDIO_VERSION, packageSpec } from './version.mjs';
+
+export const COMPAT_DATE = '2026-06-01';
+export const WRANGLER_VERSION = '4.126.0';
+
+export function slugify(name) {
+  return String(name ?? '').normalize('NFKD').replace(/[̀-ͯ]/g, '').toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 40).replace(/-+$/g, '') || 'studio';
+}
+
+/** The Worker config, generated so a later deploy can rewrite exactly what it owns. */
+export function wranglerConfig({ worker, name, d1, d1Id = null, r2 = null }) {
+  const config = {
+    $schema: '../node_modules/wrangler/config-schema.json',
+    name: worker,
+    main: 'src/worker.mjs',
+    compatibility_date: COMPAT_DATE,
+    workers_dev: true,
+    preview_urls: false,
+    assets: { directory: './dist', binding: 'ASSETS', run_worker_first: true },
+    durable_objects: { bindings: [{ name: 'TABLE', class_name: 'Table' }, { name: 'LOBBY', class_name: 'Lobby' }] },
+    migrations: [{ tag: 'v1', new_sqlite_classes: ['Table', 'Lobby'] }],
+    d1_databases: [{ binding: 'DB', database_name: d1, ...(d1Id ? { database_id: d1Id } : {}), migrations_dir: 'migrations' }],
+    ...(r2 ? { r2_buckets: [{ binding: 'MEDIA', bucket_name: r2 }] } : {}),
+    vars: { STUDIO_NAME: name },
+    observability: { enabled: true },
+  };
+  return `// This studio's site on its own Cloudflare account (written by homie-studio; \`homie-studio deploy\`
+// fills in the D1 id, and drops the R2 binding when the account has no R2).
+${JSON.stringify(config, null, 2)}
+`;
+}
+
+function agentsMd({ name, slug }) {
+  return `# ${name}
+
+This folder is a game studio: **${name}** (\`${slug}\`). It is one repository.
+Its games, music, videos and posts live here; its website and public game rooms
+run on the studio's **own Cloudflare account** (a Worker, D1, R2, and the
+Table/Lobby Durable Objects), built from \`@homie-rocks/studio\`, pinned in
+\`package.json\`. The homie.rocks directory lists its games; homie.rocks does
+not host them.
+
+## Layout
+
+| Path | What it is |
+| --- | --- |
+| \`games/<id>/\` | One game: \`game.json\` (id, name, blurb, players, round length), \`index.html\`, \`src/main.ts\`. |
+| \`music/\`, \`videos/\` | \`manifest.json\` lists each file and its R2 key. Large files go to R2 (\`npx --no-install homie-studio media put <file>\`), never into git. |
+| \`posts/\` | Markdown the studio publishes. |
+| \`site/\` | The studio's Worker (\`src/worker.mjs\`), D1 migrations, \`wrangler.jsonc\`. |
+| \`studio.json\` | The studio's name, slug and Cloudflare resource names. |
+| \`.claude/skills/\` | Skills only this studio uses. Homie's own skills come from the Homie plugin. |
+
+## Commands (all through the pinned CLI in node_modules)
+
+Use \`npm run <script>\` or \`npx --no-install homie-studio <command>\`: \`--no-install\` makes sure it is this
+studio's pinned copy, never a registry lookup of the bare name.
+
+- \`npx --no-install homie-studio game new <id> --from gem-rush --name "<Name>"\` — a new game from a
+  multiplayer starter (one live public room from its first build, bots fill seats).
+- \`npm run build\` — bundle every game into \`site/dist\`.
+- \`npm run dev\` — the whole site locally (pages, the netplay relay in a local
+  Durable Object, D1): open the printed address in two browsers and they share a room.
+- \`npx --no-install homie-studio check <id> --url <site>\` — two headless browsers press Play and must
+  land in the same room and finish a round. Run it before you say a game works.
+- \`npm run deploy\` — the site on this studio's Cloudflare (Workers, D1, R2).
+  If Wrangler is not signed in, run \`npx wrangler login\`: the person approves once in
+  their browser. It never overwrites a Worker or database this studio did not create.
+- \`npx --no-install homie-studio publish\` — list this studio's games in the homie.rocks directory
+  (or call the Homie MCP tool \`studio_publish\`).
+
+## Making games
+
+- Every game is multiplayer on the web through the netplay contract
+  (\`node_modules/@homie-rocks/studio/netplay/NETPLAY.md\`): every browser renders the game
+  itself, one browser hosts the rules, strangers meet in public rooms, bots fill empty
+  seats, anyone arriving takes a bot's place, rounds end and restart on their own.
+- Import it as \`import { createNetplay } from '@homie-rocks/studio/netplay'\`.
+- Phones and computers: touch controls on phones only, keys on computers; keep the
+  centre of the screen clear during play.
+- Change a game in small steps, build, and look at it (\`dev\`, then \`check\`).
+- A game's id is its URL (\`/<id>/\`); keep it once published.
+
+## Rules
+
+- Keys stay in the providers' own logins (Wrangler, ElevenLabs, fal) or the OS
+  keychain. Never write a key, token or password into this repository.
+- Never touch a Cloudflare resource this studio did not create (\`studio.json\` says which).
+- Nothing in this studio needs \`~/.homie\` or a Homie box.
+`;
+}
+
+function claudeMd() {
+  return `@AGENTS.md
+
+<!-- Claude Code reads AGENTS.md through the import above (the documented way to share it with Codex).
+Claude-only notes go below this line. -->
+`;
+}
+
+function readme({ name }) {
+  return `# ${name}
+
+A game studio made with [Homie](https://homie.rocks). Open this folder in Claude Code or Codex
+and ask for a game; \`AGENTS.md\` says how everything here works.
+`;
+}
+
+const MIGRATION = `-- A studio's own D1: the directory claim, and every finished round of every public room.
+CREATE TABLE IF NOT EXISTS meta (
+  key TEXT PRIMARY KEY,
+  value TEXT NOT NULL
+);
+CREATE TABLE IF NOT EXISTS rounds (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  game TEXT NOT NULL,
+  room TEXT NOT NULL,
+  n INTEGER NOT NULL,
+  humans INTEGER NOT NULL,
+  bots INTEGER NOT NULL,
+  results TEXT NOT NULL,
+  at TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS rounds_game_at ON rounds (game, at);
+`;
+
+const GITIGNORE = `node_modules/
+site/dist/
+site/.wrangler/
+.wrangler/
+.dev.vars
+.env
+*.log
+# Large media lives in this studio's R2; the manifests beside it are committed.
+music/**/*.wav
+music/**/*.mp3
+music/**/*.flac
+videos/**/*.mp4
+videos/**/*.mov
+videos/**/*.webm
+`;
+
+/** Every file a new studio gets, relative to its folder. */
+export function studioFiles({ name, slug, homie }) {
+  const worker = slug;
+  const studio = {
+    name, slug,
+    homie: { studio: STUDIO_VERSION, directory: homie },
+    cloudflare: { worker, d1: `${slug}-db`, r2: `${slug}-media`, accountId: null, url: null, created: [] },
+  };
+  const pkg = {
+    name: `${slug}-studio`,
+    private: true,
+    type: 'module',
+    scripts: { dev: 'homie-studio dev', build: 'homie-studio build', deploy: 'homie-studio deploy', check: 'homie-studio check', studio: 'homie-studio' },
+    devDependencies: { '@homie-rocks/studio': packageSpec(homie), wrangler: WRANGLER_VERSION },
+  };
+  return {
+    'AGENTS.md': agentsMd({ name, slug }),
+    'CLAUDE.md': claudeMd(),
+    'README.md': readme({ name }),
+    'studio.json': `${JSON.stringify(studio, null, 2)}\n`,
+    'package.json': `${JSON.stringify(pkg, null, 2)}\n`,
+    '.gitignore': GITIGNORE,
+    'games/README.md': 'One folder per game. Start one with `npx --no-install homie-studio game new <id> --from gem-rush`.\n',
+    'music/README.md': 'Songs and stems. `manifest.json` lists them; the files themselves go to R2 with `npx --no-install homie-studio media put`.\n',
+    'music/manifest.json': '{ "items": [] }\n',
+    'videos/README.md': 'Trailers and clips. `manifest.json` lists them; the files themselves go to R2 with `npx --no-install homie-studio media put`.\n',
+    'videos/manifest.json': '{ "items": [] }\n',
+    'posts/README.md': 'Markdown posts this studio publishes, one file each.\n',
+    'site/src/worker.mjs': `// This studio's site: pages, public rooms (Table + Lobby Durable Objects), D1 and R2.
+// The code is @homie-rocks/studio's, pinned in package.json, so an update never changes a published game by surprise.
+export { default, Table, Lobby } from '@homie-rocks/studio/worker';
+`,
+    'site/migrations/0001_studio.sql': MIGRATION,
+    'site/wrangler.jsonc': wranglerConfig({ worker, name, d1: studio.cloudflare.d1, r2: studio.cloudflare.r2 }),
+    '.claude/skills/.gitkeep': '',
+  };
+}
+
+function insideGit(dir) {
+  try { return execFileSync('git', ['rev-parse', '--is-inside-work-tree'], { cwd: dir, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim() === 'true'; } catch { return false; }
+}
+
+export function newStudio(folder, { name, homie, slug: askedSlug, install = true } = {}) {
+  if (typeof folder !== 'string' || !folder.trim()) throw new Error('name the folder for the new studio, e.g. `homie-studio new ~/studios/night-owls --name "Night Owls"`. Nothing was written.');
+  if (!name || !String(name).trim()) throw new Error('give the studio a name: --name "Night Owls". Nothing was written.');
+  const dir = resolve(folder.replace(/^~(?=\/|$)/, homedir()));
+  const home = realpathSync(homedir());
+  let real = null;
+  try { real = realpathSync(dir); } catch { /* new */ }
+  const at = real ?? dir;
+  if (at === home || at === '/' || home.startsWith(`${at}/`)) throw new Error(`${at} is your home folder or above it; a studio needs its own folder. Nothing was written.`);
+  if (real) {
+    if (!statSync(real).isDirectory()) throw new Error(`${real} is a file. Nothing was written.`);
+    const entries = readdirSync(real).filter((n) => n !== '.DS_Store' && n !== '.git');
+    if (entries.length) throw new Error(`${real} is not empty (${entries.slice(0, 5).join(', ')}${entries.length > 5 ? ', …' : ''}). A new studio goes in a new or empty folder. Nothing was written.`);
+  }
+  const slug = slugify(askedSlug || name);
+  const files = studioFiles({ name: String(name).trim(), slug, homie: homie || 'https://homie.rocks' });
+  mkdirSync(dir, { recursive: true });
+  const wrote = [];
+  for (const [rel, content] of Object.entries(files)) {
+    const path = join(dir, rel);
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, content);
+    wrote.push(rel);
+  }
+  let git = 'already inside a git repository';
+  if (!insideGit(dir)) {
+    try { execFileSync('git', ['init', '-q'], { cwd: dir, stdio: 'ignore' }); git = 'initialised'; wrote.push('.git/'); } catch { git = 'git not found'; }
+  }
+  // Install the pinned @homie-rocks/studio and wrangler now, so every later `npx homie-studio` is this studio's own
+  // copy and never a registry lookup of the bare name.
+  let installed = 'skipped (--no-install): run npm install before any other command';
+  if (install) {
+    try {
+      execFileSync('npm', ['install', '--no-audit', '--no-fund'], { cwd: dir, stdio: ['ignore', 'ignore', 'pipe'], env: { ...process.env, npm_config_update_notifier: 'false' } });
+      installed = 'npm install done';
+      wrote.push('node_modules/', 'package-lock.json');
+    } catch (error) { installed = `npm install failed (${String(error.stderr ?? error.message).trim().split('\n').slice(-2).join(' ')}): run it in the studio folder`; }
+  }
+  const q = JSON.stringify(realpathSync(dir));
+  return { ok: true, command: 'new', dir: realpathSync(dir), name, slug, wrote, git, installed, studio: STUDIO_VERSION, next: [
+    `cd ${q}${install ? '' : ' && npm install'}`,
+    'npx --no-install homie-studio game new <id> --from gem-rush --name "<Game Name>"',
+    'npm run dev   (then: npx --no-install homie-studio check <id> --url http://127.0.0.1:8787)',
+    'npm run deploy   (then the Homie MCP tool studio_publish, or: npx --no-install homie-studio publish)',
+  ] };
+}
+
+export const _test = { relative };

package/lib/studio.mjs

@@ -0,0 +1,102 @@
+/**
+ * Finding and reading a studio: the folder with studio.json at or above the
+ * current directory, and its games.
+ */
+import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+export const GAME_ID = /^[a-z0-9][a-z0-9-]{0,39}$/;
+const RESERVED_IDS = new Set(['api', 'media', 'games', 'assets', '_homie', 'well-known', 'index', 'play', 'studio', 'studios']);
+
+export function findStudio(from = process.cwd()) {
+  let at = resolve(from);
+  for (;;) {
+    if (existsSync(join(at, 'studio.json'))) return at;
+    const up = dirname(at);
+    if (up === at) return null;
+    at = up;
+  }
+}
+
+export function requireStudio(from) {
+  const root = findStudio(from);
+  if (!root) throw new Error('not inside a studio (no studio.json here or above). Make one: npx homie-studio new <folder> --name "<Studio Name>"');
+  return root;
+}
+
+export function readStudio(root) { return JSON.parse(readFileSync(join(root, 'studio.json'), 'utf8')); }
+export function writeStudio(root, studio) { writeFileSync(join(root, 'studio.json'), `${JSON.stringify(studio, null, 2)}\n`); }
+
+export function listGames(root) {
+  const dir = join(root, 'games');
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir, { withFileTypes: true })
+    .filter((d) => d.isDirectory() && existsSync(join(dir, d.name, 'game.json')))
+    .map((d) => {
+      const meta = JSON.parse(readFileSync(join(dir, d.name, 'game.json'), 'utf8'));
+      return { ...meta, id: meta.id ?? d.name, dir: join(dir, d.name) };
+    })
+    .sort((a, b) => a.id.localeCompare(b.id));
+}
+
+export function starters() {
+  const dir = join(PACKAGE_ROOT, 'starters');
+  return readdirSync(dir, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => {
+    const meta = JSON.parse(readFileSync(join(dir, d.name, 'game.json'), 'utf8'));
+    return { id: d.name, name: meta.name, blurb: meta.blurb, players: meta.players, roundSeconds: meta.roundSeconds };
+  });
+}
+
+/** `homie-studio game new <id> --from <starter> --name "<Name>"`: a starter copied in as this studio's own game. */
+export function newGame(root, id, { from = 'gem-rush', name } = {}) {
+  if (!GAME_ID.test(String(id ?? '')) || RESERVED_IDS.has(id)) throw new Error(`a game id is lowercase letters, digits and hyphens, up to 40, and not one of ${[...RESERVED_IDS].join(', ')} (got ${JSON.stringify(id)})`);
+  const src = join(PACKAGE_ROOT, 'starters', from);
+  if (!existsSync(join(src, 'game.json'))) throw new Error(`no starter "${from}"; starters: ${starters().map((s) => s.id).join(', ')}`);
+  const dest = join(root, 'games', id);
+  if (existsSync(dest)) throw new Error(`games/${id} already exists; pick another id or change that game`);
+  cpSync(src, dest, { recursive: true });
+  const meta = JSON.parse(readFileSync(join(dest, 'game.json'), 'utf8'));
+  meta.id = id;
+  if (name) meta.name = String(name).slice(0, 60);
+  meta.from = { starter: from, studio: JSON.parse(readFileSync(join(PACKAGE_ROOT, 'package.json'), 'utf8')).version };
+  writeFileSync(join(dest, 'game.json'), `${JSON.stringify(meta, null, 2)}\n`);
+  const main = join(dest, meta.entry ?? 'src/main.ts');
+  if (existsSync(main)) writeFileSync(main, readFileSync(main, 'utf8').replace(new RegExp(`game: '${from}'`, 'g'), `game: '${id}'`));
+  const html = join(dest, 'index.html');
+  if (name && existsSync(html)) writeFileSync(html, readFileSync(html, 'utf8').replace(/<title>[^<]*<\/title>/, `<title>${String(name).replace(/[<&]/g, '')}</title>`));
+  return { ok: true, command: 'game new', id, from, dir: dest, files: readdirSync(dest, { recursive: true }).map(String) };
+}
+
+/** `homie-studio game remix <source.json url> --id <new id>`: a shared game brought in as this studio's own. */
+export async function remixGame(root, source, id, { name } = {}) {
+  if (!GAME_ID.test(String(id ?? '')) || RESERVED_IDS.has(id)) throw new Error('give the new game an id: --id <lowercase-id>');
+  const dest = join(root, 'games', id);
+  if (existsSync(dest)) throw new Error(`games/${id} already exists`);
+  let url;
+  try { url = new URL(source); } catch { throw new Error('usage: homie-studio game remix <https://studio.site/games/<id>/source.json> --id <new id>'); }
+  if (url.protocol !== 'https:' && !['127.0.0.1', 'localhost'].includes(url.hostname)) throw new Error('a remix source is an https:// address');
+  const res = await fetch(url, { signal: AbortSignal.timeout(20_000) });
+  if (!res.ok) throw new Error(`${url} answered ${res.status}`);
+  const body = await res.json();
+  if (body?.kind !== 'homie-game-source' || !body.files || typeof body.files !== 'object') throw new Error('that address is not a shared Homie game source');
+  const wrote = [];
+  for (const [rel, text] of Object.entries(body.files)) {
+    if (typeof text !== 'string' || rel.includes('..') || rel.startsWith('/') || !/^[A-Za-z0-9._/-]+$/.test(rel)) continue;
+    const path = join(dest, rel);
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, text);
+    wrote.push(rel);
+  }
+  if (!existsSync(join(dest, 'game.json'))) throw new Error('the shared source has no game.json');
+  const meta = JSON.parse(readFileSync(join(dest, 'game.json'), 'utf8'));
+  const from = meta.id;
+  meta.remixOf = { source: String(url), id: from, name: meta.name };
+  meta.id = id;
+  if (name) meta.name = String(name).slice(0, 60);
+  writeFileSync(join(dest, 'game.json'), `${JSON.stringify(meta, null, 2)}\n`);
+  const main = join(dest, meta.entry ?? 'src/main.ts');
+  if (existsSync(main) && from) writeFileSync(main, readFileSync(main, 'utf8').replace(new RegExp(`game: '${from}'`, 'g'), `game: '${id}'`));
+  return { ok: true, command: 'game remix', id, from: String(url), files: wrote };
+}

package/lib/version.mjs

@@ -0,0 +1,17 @@
+/**
+ * The one place @homie-rocks/studio says which version it is and where that exact
+ * version lives. A studio pins this tarball (package.json + package-lock
+ * integrity), so a published game never changes because Homie changed.
+ */
+import { readFileSync } from 'node:fs';
+
+const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+export const STUDIO_VERSION = pkg.version;
+
+/** The pinned tarball of this version, on a Homie directory (homie.rocks by default). */
+export function tarballUrl(base = 'https://homie.rocks', version = STUDIO_VERSION) {
+  return `${String(base).replace(/\/+$/, '')}/npm/homie-studio-${version}.tgz`;
+}
+
+/** What a studio's package.json names: until @homie-rocks/studio is on the npm registry, its versioned tarball URL. */
+export function packageSpec(base) { return tarballUrl(base); }