@myvillage/cli 2.17.0 → 2.18.0

package/README.md

@@ -19,6 +19,10 @@ myvillage login
 # Create a new game project
 myvillage create-game
 
+# Or bring a web game you already have into MyVillage
+# (shows what will change and asks first; --dry-run only shows)
+myvillage init-game ./my-game
+
 # Deploy to the platform
 myvillage deploy
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@myvillage/cli",
-  "version": "2.17.0",
+  "version": "2.18.0",
   "description": "MyVillageOS CLI for community developers",
   "type": "module",
   "bin": {

package/src/commands/create-game.js

@@ -61,8 +61,8 @@ export async function createGameCommand(options = {}) {
           name: 'orientation',
           message: 'Where will this game play?',
           choices: [
-            { name: 'Portrait — muni mobile app + web (plays everywhere)', value: 'portrait' },
-            { name: 'Landscape — web only (mvp-video-games)', value: 'landscape' },
+            { name: 'Portrait — muni mobile app + web', value: 'portrait' },
+            { name: 'Landscape — muni mobile app (turned sideways) + web; Unity: web only', value: 'landscape' },
           ],
         },
       ])

package/src/commands/init-game.js

@@ -0,0 +1,200 @@
+import { existsSync, statSync } from 'fs';
+import { resolve, basename } from 'path';
+import chalk from 'chalk';
+import inquirer from 'inquirer';
+import { brand } from '../utils/brand.js';
+import {
+  inspectGameFolder,
+  convertToGame,
+  defaultCopyDir,
+  updatePlatformFiles,
+  GAME_CATEGORIES,
+  TARGET_AGES,
+} from '../utils/game-init.js';
+
+// `myvillage init-game [dir]` — bring an existing web game into MyVillage, or
+// bring a MyVillage game's platform files up to this CLI's. Shows what will
+// change and asks before writing anything (--yes skips the question, --dry-run
+// only shows). MVP Studio runs the same code in-process (src/utils/game-init.js).
+//
+// A web game is converted into a new folder next to it (<name>-myvillage) so
+// the original stays as it was; --into picks the folder, --in-place converts
+// the original instead.
+
+function out(json, payload) {
+  if (json) console.log(JSON.stringify(payload));
+}
+
+function fail(json, msg) {
+  if (json) console.log(JSON.stringify({ ok: false, error: msg }));
+  else console.log(chalk.red(`\n  ✗ ${msg}`));
+  process.exitCode = 1;
+}
+
+function printChanges(changes) {
+  for (const c of changes) {
+    const verb = c.action === 'create' ? brand.green('+ add   ') : brand.gold('~ update');
+    console.log(`    ${verb} ${c.path}  ${brand.teal(c.summary)}`);
+  }
+}
+
+function printNotes(notes) {
+  if (!notes.length) return;
+  console.log();
+  console.log(brand.gold('  Still needed (left for you):'));
+  for (const n of notes) console.log(`    • ${n}`);
+}
+
+async function confirm(message) {
+  const { ok } = await inquirer.prompt([{ type: 'confirm', name: 'ok', message, default: true }]);
+  return ok;
+}
+
+export async function initGameCommand(dirArg, options = {}) {
+  const json = !!options.json;
+  const dryRun = !!options.dryRun;
+  // JSON means a program is driving: never prompt.
+  const ask = !json && !options.yes;
+  const dir = resolve(dirArg || options.dir || process.cwd());
+  if (!existsSync(dir) || !statSync(dir).isDirectory()) return fail(json, `No such folder: ${dir}`);
+
+  let info;
+  try {
+    info = inspectGameFolder(dir);
+  } catch (err) {
+    return fail(json, err.message);
+  }
+
+  if (info.kind === 'unsupported') {
+    if (!json) return fail(json, info.reason);
+    process.exitCode = 1;
+    return out(json, { ok: false, kind: info.kind, dir, error: info.reason });
+  }
+
+  if (info.kind === 'unity') {
+    if (json) return out(json, { ok: true, kind: 'unity', dir, dryRun, changes: [], notes: [] });
+    console.log(brand.green(`\n  ✓ ${info.name} is a MyVillage Unity game. Nothing to set up here.`));
+    return;
+  }
+
+  // ── Already a MyVillage game: refresh its platform files ──
+  if (info.kind === 'myvillage') {
+    if (dryRun || !info.changes.length) {
+      if (json) return out(json, { ok: true, kind: 'myvillage', dir, name: info.name, dryRun: true, changes: info.changes, notes: [] });
+      if (!info.changes.length) {
+        console.log(brand.green(`\n  ✓ ${info.name} already has the latest MyVillage platform files.`));
+      } else {
+        console.log(`\n  ${info.name} has older MyVillage platform files:\n`);
+        printChanges(info.changes);
+        console.log(brand.teal('\n  Run without --dry-run to update them.'));
+      }
+      return;
+    }
+    if (ask) {
+      console.log(`\n  ${info.name} has older MyVillage platform files. This will:\n`);
+      printChanges(info.changes);
+      console.log();
+      if (!(await confirm('Update them?'))) return;
+    }
+    try {
+      const res = updatePlatformFiles(dir);
+      if (json) return out(json, { ok: true, kind: 'myvillage', dir, name: info.name, dryRun: false, changes: res.changes, notes: [] });
+      console.log(brand.green(`\n  ✓ Updated ${res.changes.map((c) => c.path).join(', ')}`));
+    } catch (err) {
+      fail(json, err.message);
+    }
+    return;
+  }
+
+  // ── A web project: convert it ──
+  const given = {
+    name: options.name,
+    description: options.description,
+    category: options.category,
+    orientation: options.orientation,
+    targetAge: options.targetAge,
+  };
+  let details = { ...info.defaults };
+  for (const [k, v] of Object.entries(given)) if (v !== undefined) details[k] = String(v);
+  if (options.into && options.inPlace) return fail(json, 'Use --into or --in-place, not both.');
+  let into = options.inPlace ? undefined : resolve(options.into || defaultCopyDir(dir));
+
+  if (ask && !dryRun) {
+    console.log(`\n  ${brand.gold(dir)} is a web project that isn't a MyVillage game yet.\n`);
+    const prompts = [];
+    if (given.name === undefined) prompts.push({ type: 'input', name: 'name', message: 'Game name:', default: details.name });
+    if (given.description === undefined) prompts.push({ type: 'input', name: 'description', message: 'Description:', default: details.description });
+    if (given.category === undefined)
+      prompts.push({ type: 'list', name: 'category', message: 'What kind of game is it?', choices: GAME_CATEGORIES, default: details.category });
+    if (given.orientation === undefined)
+      prompts.push({
+        type: 'list',
+        name: 'orientation',
+        message: 'Where will it play?',
+        choices: [
+          { name: 'Portrait — muni mobile app + web', value: 'portrait' },
+          { name: 'Landscape — muni mobile app (turned sideways) + web', value: 'landscape' },
+        ],
+        default: details.orientation,
+      });
+    if (given.targetAge === undefined)
+      prompts.push({ type: 'list', name: 'targetAge', message: 'Target age group:', choices: TARGET_AGES, default: details.targetAge });
+    if (!options.into && !options.inPlace)
+      prompts.push({
+        type: 'list',
+        name: 'where',
+        message: 'Where should the MyVillage version go?',
+        choices: [
+          { name: `A new folder: ${basename(into)} (your original stays as it is)`, value: 'copy' },
+          { name: 'This folder (change it in place)', value: 'in-place' },
+        ],
+        default: 'copy',
+      });
+    const { where, ...answers } = await inquirer.prompt(prompts);
+    details = { ...details, ...answers };
+    if (where === 'in-place') into = undefined;
+  }
+
+  let plan;
+  try {
+    plan = convertToGame(dir, details, { dryRun: true, into });
+  } catch (err) {
+    return fail(json, err.message);
+  }
+
+  if (dryRun) {
+    if (json) return out(json, { ok: true, kind: 'web', source: dir, name: details.name, defaults: info.defaults, dryRun: true, ...plan });
+    console.log(`\n  Bringing ${details.name} into MyVillage would${into ? ` copy it to ${brand.gold(into)} and then` : ''}:\n`);
+    printChanges(plan.changes);
+    printNotes(plan.notes);
+    console.log(brand.teal('\n  Run without --dry-run to make these changes.'));
+    return;
+  }
+
+  if (ask) {
+    console.log(into ? `\n  This will copy the game to ${brand.gold(into)}, then in the copy:\n` : `\n  This will:\n`);
+    printChanges(plan.changes);
+    printNotes(plan.notes);
+    console.log(brand.teal(into ? '\n  The original folder isn\'t changed. node_modules, build output and git history aren\'t copied.' : "\n  Your game's own code isn't changed."));
+    console.log();
+    if (!(await confirm('Make these changes?'))) return;
+  }
+
+  try {
+    const res = convertToGame(dir, details, { into });
+    if (json) return out(json, { ok: true, kind: 'web', source: dir, name: details.name, dryRun: false, ...res });
+    console.log(brand.green(`\n  ✓ ${details.name} is set up as a MyVillage game${into ? ` in ${res.dir}` : ''}.`));
+    if (into) console.log(brand.teal(`    cd ${res.dir} && npm install`));
+    printNotes(res.notes);
+    console.log();
+    console.log(brand.teal('  Next, connect the game itself (or let MVP Studio\'s AI do it: open the game → Design):'));
+    console.log(`    1. ${brand.gold("import { MyVillageGame } from './myvillage-game.js'")} where the game starts`);
+    console.log(`    2. ${brand.gold('MyVillageGame.ready()')} once it's playable`);
+    console.log(`    3. ${brand.gold('MyVillageGame.complete({ score, won })')} on every way it can end`);
+    console.log(`    4. ${brand.gold('npm run build')}, then ${brand.gold('myvillage deploy')}`);
+    console.log(brand.teal('  AGENTS.md has the full rules (phone layout, play time).'));
+    console.log();
+  } catch (err) {
+    fail(json, err.message);
+  }
+}

package/src/index.js

@@ -16,6 +16,7 @@ import {
   apiKeyShowScopesCommand,
 } from './commands/api-key.js';
 import { createGameCommand } from './commands/create-game.js';
+import { initGameCommand } from './commands/init-game.js';
 import { createCommand } from './commands/create-app.js';
 import { deployCommand } from './commands/deploy.js';
 import { publishBookCommand } from './commands/publish-book.js';
@@ -229,6 +230,22 @@ export function run() {
     .option('--json', 'Output the result as JSON (implies non-interactive)')
     .action(createGameCommand);
 
+  program
+    .command('init-game [dir]')
+    .description('Bring an existing web game into MyVillage, or update a game\'s MyVillage platform files')
+    .option('--name <name>', 'Game name (defaults to package.json)')
+    .option('--description <text>', 'Game description')
+    .option('--category <category>', 'education | action | adventure | puzzle | quiz | exploration | narrative | other')
+    .option('--orientation <orientation>', 'portrait | landscape')
+    .option('--target-age <age>', 'under-5 | 6-12 | 13-and-over')
+    .option('--dir <path>', 'Project folder (defaults to cwd)')
+    .option('--into <path>', 'Convert into this new folder (default: <folder>-myvillage next to it)')
+    .option('--in-place', 'Convert the folder itself instead of a copy')
+    .option('--dry-run', 'Show what would change and write nothing')
+    .option('-y, --yes', "Don't ask: use the defaults and make the changes")
+    .option('--json', 'Output the result as JSON (implies --yes)')
+    .action(initGameCommand);
+
   program
     .command('create')
     .description('Create a new application or game')

package/src/utils/game-init.js

@@ -0,0 +1,379 @@
+import { existsSync, readFileSync, writeFileSync, mkdirSync, copyFileSync, cpSync, readdirSync, rmSync } from 'fs';
+import { join, basename, dirname, resolve, relative, isAbsolute, sep } from 'path';
+import { installGameToolkit, refreshGameToolkit } from './game-toolkit.js';
+import { generateGameAgents, generateMinimalViteConfig, starterThumbnailPath } from './templates.js';
+
+// Bringing a web game that wasn't made with MyVillage into the platform
+// (`myvillage init-game`), and keeping a MyVillage game's platform files current.
+// MVP Studio imports this module in-process, so it must stay free of chalk,
+// inquirer and anything else that prints or prompts.
+//
+// Every entry point takes `dryRun`: the same code computes what would change
+// and makes the change, so what Studio shows before asking is exactly what
+// gets written.
+
+export const GAME_CATEGORIES = ['education', 'action', 'adventure', 'puzzle', 'quiz', 'exploration', 'narrative', 'other'];
+export const TARGET_AGES = ['under-5', '6-12', '13-and-over'];
+export const ORIENTATIONS = ['portrait', 'landscape'];
+
+const VITE_CONFIGS = ['vite.config.js', 'vite.config.mjs', 'vite.config.ts', 'vite.config.mts', 'vite.config.cjs', 'vite.config.cts'];
+const OUR_AGENTS = /^# AGENTS\.md — working on this MyVillage/;
+const AGENTS_START = '<!-- myvillage:agents:start -->';
+const AGENTS_END = '<!-- myvillage:agents:end -->';
+
+function readJson(path) {
+  try {
+    return JSON.parse(readFileSync(path, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function writeJson(path, data) {
+  writeFileSync(path, JSON.stringify(data, null, 2) + '\n');
+}
+
+function deps(pkg) {
+  return { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
+}
+
+function titleFromPackageName(raw) {
+  const bare = String(raw || '').replace(/^@[^/]+\//, '');
+  return bare
+    .split(/[-_.\s]+/)
+    .filter(Boolean)
+    .map((w) => w[0].toUpperCase() + w.slice(1))
+    .join(' ');
+}
+
+/**
+ * What kind of folder this is, and what `init-game` would do to it.
+ *
+ *   kind 'web'          a package.json project with no `myvillage` block: `changes`
+ *                       is the conversion plan, `defaults` the prefilled details
+ *   kind 'myvillage'    already a MyVillage JS game: `changes` lists platform
+ *                       files that are older than this CLI's
+ *   kind 'unity'        a MyVillage Unity game (nothing to update here)
+ *   kind 'unsupported'  anything else; `reason` says what is supported
+ */
+export function inspectGameFolder(dir) {
+  const unity = readJson(join(dir, 'myvillage.json'));
+  if (unity && unity.engine === 'unity') {
+    return { kind: 'unity', dir, name: unity.name || basename(dir), changes: [], notes: [] };
+  }
+
+  const pkgPath = join(dir, 'package.json');
+  const pkg = readJson(pkgPath);
+  if (!pkg) {
+    const looksUnity = existsSync(join(dir, 'Assets')) && existsSync(join(dir, 'ProjectSettings'));
+    const reason = existsSync(pkgPath)
+      ? "package.json isn't valid JSON, so this folder can't be read as a web game. Fix it and try again."
+      : looksUnity
+        ? 'This looks like a Unity project that wasn\'t made with MyVillage. Unity games start from New game with Engine set to Unity; bring your scenes and scripts into that project.'
+        : 'This folder isn\'t a game Studio can bring in. Studio supports web games with a package.json (built with Vite, or any tool whose `npm run build` writes a dist/ folder), and Unity games made with MyVillage.';
+    return { kind: 'unsupported', dir, reason, changes: [], notes: [] };
+  }
+
+  if (pkg.myvillage && typeof pkg.myvillage === 'object') {
+    const { changes } = updatePlatformFiles(dir, { dryRun: true });
+    return { kind: 'myvillage', dir, name: pkg.myvillage.name || pkg.name || basename(dir), changes, notes: [] };
+  }
+
+  const defaults = conversionDefaults(dir, pkg);
+  const { changes, notes } = convertToGame(dir, defaults, { dryRun: true });
+  return { kind: 'web', dir, name: defaults.name, defaults, changes, notes, copyTo: defaultCopyDir(dir) };
+}
+
+// ── Converting into a copy ──────────────────────────────────────────────────
+// By default a game is converted into a new folder next to the original, so the
+// original stays exactly as it was. Installed packages and build output aren't
+// copied (npm install / npm run build make them again), and neither is git
+// history: the copy is a new project.
+
+const SKIP_ANYWHERE = new Set(['node_modules', '.git', '.DS_Store']);
+const SKIP_AT_TOP = new Set(['dist', 'build', '.vite', '.cache', '.parcel-cache', '.turbo', '.next', 'coverage']);
+
+/** A free sibling folder for the converted copy: `<name>-myvillage`, then -2, -3… */
+export function defaultCopyDir(dir) {
+  const base = join(dirname(resolve(dir)), `${basename(resolve(dir))}-myvillage`);
+  if (!existsSync(base)) return base;
+  for (let i = 2; ; i++) if (!existsSync(`${base}-${i}`)) return `${base}-${i}`;
+}
+
+function isInside(child, parent) {
+  const rel = relative(parent, child);
+  return rel === '' || (!rel.startsWith('..') && !isAbsolute(rel));
+}
+
+/** Copy a project into `to` (which must not exist yet, or be empty). */
+export function copyGameProject(from, to) {
+  const src = resolve(from);
+  const dest = resolve(to);
+  if (isInside(dest, src)) throw new Error('The new folder can\'t be inside the game\'s own folder.');
+  if (existsSync(dest) && readdirSync(dest).length) {
+    throw new Error(`${dest} already exists and isn't empty. Pick a new folder.`);
+  }
+  cpSync(src, dest, {
+    recursive: true,
+    filter: (path) => {
+      const rel = relative(src, path);
+      if (!rel) return true;
+      const parts = rel.split(sep);
+      if (parts.some((p) => SKIP_ANYWHERE.has(p))) return false;
+      return !SKIP_AT_TOP.has(parts[0]);
+    },
+  });
+}
+
+/** The game details to prefill, from what package.json already says. */
+export function conversionDefaults(dir, pkg = readJson(join(dir, 'package.json')) || {}) {
+  const keywords = Array.isArray(pkg.keywords) ? pkg.keywords.map((k) => String(k).toLowerCase()) : [];
+  return {
+    name: String(pkg.productName || '').trim() || titleFromPackageName(pkg.name) || titleFromPackageName(basename(dir)) || 'My Game',
+    description: typeof pkg.description === 'string' ? pkg.description : '',
+    category: GAME_CATEGORIES.find((c) => keywords.includes(c)) || 'education',
+    // Portrait plays everywhere (the muni app and the web).
+    orientation: 'portrait',
+    targetAge: '6-12',
+  };
+}
+
+function normalizeDetails(details) {
+  const name = String(details.name || '').trim();
+  if (!name) throw new Error('The game needs a name.');
+  const category = String(details.category || 'education').toLowerCase();
+  if (!GAME_CATEGORIES.includes(category)) throw new Error(`Category must be one of: ${GAME_CATEGORIES.join(', ')}`);
+  const orientation = String(details.orientation || 'portrait').toLowerCase();
+  if (!ORIENTATIONS.includes(orientation)) throw new Error('Orientation must be portrait or landscape.');
+  const targetAge = String(details.targetAge || '6-12').toLowerCase();
+  if (!TARGET_AGES.includes(targetAge)) throw new Error(`Target age must be one of: ${TARGET_AGES.join(', ')}`);
+  const description = typeof details.description === 'string' ? details.description.trim() : '';
+  return { name, category, orientation, targetAge, description };
+}
+
+/**
+ * Turn a package.json web project into a MyVillage game: the `myvillage`
+ * block, the toolkit, AGENTS.md, a relative Vite base + build script, and a
+ * starter thumbnail. Never touches the game's own code, and never rewrites a
+ * build it doesn't understand (a note says what's needed instead).
+ *
+ * With `into`, the project is first copied there (see copyGameProject) and the
+ * copy is converted; the original folder isn't touched. Without it, the folder
+ * itself is converted.
+ *
+ * Returns { dir, changes: [{ path, action: 'create'|'update', summary }], notes },
+ * where `dir` is the folder that was (or would be) converted.
+ */
+export function convertToGame(dir, details, { dryRun = false, into } = {}) {
+  if (!into) return { dir, ...convertInPlace(dir, details, { dryRun }) };
+  // The copy would get exactly the original's plan (it's the same files).
+  if (dryRun) return { dir: resolve(into), ...convertInPlace(dir, details, { dryRun: true }) };
+  // Check the details before copying anything.
+  normalizeDetails(details);
+  const dest = resolve(into);
+  const existed = existsSync(dest);
+  copyGameProject(dir, dest);
+  try {
+    return { dir: dest, ...convertInPlace(dest, details) };
+  } catch (err) {
+    // Don't leave a half-converted copy behind.
+    if (!existed) rmSync(dest, { recursive: true, force: true });
+    throw err;
+  }
+}
+
+function convertInPlace(dir, details, { dryRun = false } = {}) {
+  const pkgPath = join(dir, 'package.json');
+  const pkg = readJson(pkgPath);
+  if (!pkg) throw new Error('No readable package.json in this folder.');
+  if (pkg.myvillage) throw new Error('This folder is already a MyVillage game.');
+  const game = normalizeDetails(details);
+
+  const changes = [];
+  const notes = [];
+  const change = (path, action, summary) => changes.push({ path, action, summary });
+
+  const isVite = !!deps(pkg).vite || VITE_CONFIGS.some((f) => existsSync(join(dir, f)));
+
+  // ── package.json ──
+  const pkgSummary = ['add the MyVillage details (name, kind, orientation, ages)'];
+  const scripts = { ...(pkg.scripts || {}) };
+  if (isVite) {
+    if (!scripts.build) {
+      scripts.build = 'vite build';
+      pkgSummary.push('add a `build` script (vite build)');
+    } else if (!/\bvite\b/.test(scripts.build)) {
+      notes.push(`The \`build\` script ("${scripts.build}") doesn't run Vite. Deploy runs \`npm run build\` and uploads the dist/ folder it makes, so check that it still does.`);
+    }
+    if (!scripts.dev) {
+      scripts.dev = 'vite';
+      pkgSummary.push('add a `dev` script for the preview');
+    }
+  } else if (!scripts.build) {
+    notes.push("This project doesn't use Vite and has no `build` script. Deploy runs `npm run build` and uploads the dist/ folder it makes (with an index.html and relative asset paths), so add a build that does that. Vite is the easiest way.");
+  } else {
+    notes.push(`This project doesn't use Vite, so its build was left alone. Deploy runs \`npm run build\` ("${scripts.build}") and uploads dist/: make sure it writes there, with index.html at the top and asset paths that don't start with "/".`);
+  }
+  if (!isVite && !scripts.dev) {
+    notes.push('There is no `dev` script, so Studio can\'t show a live preview until one is added.');
+  }
+
+  const banner = ['assets/banner.png', 'assets/banner.jpg'].find((p) => existsSync(join(dir, p)));
+  const myvillage = {
+    name: game.name,
+    gameId: null,
+    gameType: 'custom',
+    category: game.category,
+    engine: deps(pkg).three ? 'three' : 'web',
+    // Brought in with init-game (not scaffolded): picks the AGENTS.md guide.
+    converted: true,
+    targetAge: game.targetAge,
+    orientation: game.orientation,
+    aspectRatio: game.orientation === 'portrait' ? '9:16' : '16:9',
+    assets: { thumbnail: 'assets/thumbnail.png', ...(banner && { banner }) },
+    villages: [],
+    lastDeployed: null,
+  };
+  const nextPkg = { ...pkg };
+  if (game.description && game.description !== pkg.description) nextPkg.description = game.description;
+  if (Object.keys(scripts).length) nextPkg.scripts = scripts;
+  nextPkg.myvillage = myvillage;
+  change('package.json', 'update', pkgSummary.join('; '));
+
+  // ── Vite config ──
+  if (isVite) {
+    const configFile = VITE_CONFIGS.find((f) => existsSync(join(dir, f)));
+    if (!configFile) {
+      const file = pkg.type === 'module' ? 'vite.config.js' : 'vite.config.mjs';
+      change(file, 'create', "use relative asset paths (base: './') so the game loads from MyVillage");
+      if (!dryRun) writeFileSync(join(dir, file), generateMinimalViteConfig());
+    } else {
+      const fixed = withRelativeBase(readFileSync(join(dir, configFile), 'utf8'));
+      if (fixed.text) {
+        change(configFile, 'update', fixed.summary);
+        if (!dryRun) writeFileSync(join(dir, configFile), fixed.text);
+      } else if (fixed.note) {
+        notes.push(`${configFile}: ${fixed.note}`);
+      }
+      const outDir = /\boutDir\s*:\s*(['"`])([^'"`]+)\1/.exec(readFileSync(join(dir, configFile), 'utf8'))?.[2];
+      if (outDir && !['dist', './dist', 'dist/', './dist/'].includes(outDir)) {
+        notes.push(`${configFile} builds into "${outDir}", but deploy uploads dist/. Change build.outDir to 'dist'.`);
+      }
+    }
+  }
+
+  // ── Toolkit ──
+  const hadToolkit = new Set(['src/myvillage-game.js', 'src/myvillage-realtime.js'].filter((p) => existsSync(join(dir, p))));
+  const toolkit = installGameToolkit(dir, { dryRun });
+  for (const path of toolkit.changed) {
+    change(path, hadToolkit.has(path) ? 'update' : 'create',
+      path.endsWith('myvillage-game.js')
+        ? 'the MyVillage toolkit: ready(), complete() and automatic play time'
+        : 'multiplayer support the toolkit loads when a game asks for it');
+  }
+  for (const path of toolkit.conflicts) {
+    notes.push(`${path} already exists and isn't the MyVillage toolkit, so it was left alone. Rename it, then run this again.`);
+  }
+
+  // ── AGENTS.md ──
+  const agents = agentsMdChange(dir, myvillage, { slug: pkg.name, description: nextPkg.description, dryRun });
+  if (agents) change('AGENTS.md', agents.action, agents.summary);
+
+  // ── Cover art ──
+  if (!existsSync(join(dir, 'assets', 'thumbnail.png'))) {
+    change('assets/thumbnail.png', 'create', 'starter cover art (swap it for your own any time)');
+    if (!dryRun) {
+      mkdirSync(join(dir, 'assets'), { recursive: true });
+      copyFileSync(starterThumbnailPath(), join(dir, 'assets', 'thumbnail.png'));
+    }
+  }
+
+  // package.json last, so a failure above leaves the folder still unconverted.
+  if (!dryRun) writeJson(pkgPath, nextPkg);
+  return { changes, notes };
+}
+
+/**
+ * Bring a MyVillage JS game's platform files (the toolkit and AGENTS.md) up to
+ * this CLI's. `deploy` already refreshes the toolkit; AGENTS.md only changes here.
+ */
+export function updatePlatformFiles(dir, { dryRun = false } = {}) {
+  const pkg = readJson(join(dir, 'package.json'));
+  if (!pkg || !pkg.myvillage) throw new Error('Not a MyVillage web game (no `myvillage` block in package.json).');
+
+  const changes = [];
+  for (const path of refreshGameToolkit(dir, { dryRun })) {
+    changes.push({ path, action: 'update', summary: 'the latest MyVillage toolkit' });
+  }
+  const agents = agentsMdChange(dir, pkg.myvillage, { slug: pkg.name, description: pkg.description, dryRun });
+  if (agents) changes.push({ path: 'AGENTS.md', ...agents });
+  return { changes, notes: [] };
+}
+
+/**
+ * Write (or plan) the AGENTS.md this CLI generates for the game. A file that
+ * is ours is replaced; someone else's AGENTS.md keeps its text and gets ours as
+ * a marked section at the end. Returns null when it's already current.
+ */
+function agentsMdChange(dir, myvillage, { slug, description, dryRun }) {
+  const path = join(dir, 'AGENTS.md');
+  const latest = generateGameAgents(myvillage, { slug, description });
+  const section = `${AGENTS_START}\n${latest.trimEnd()}\n${AGENTS_END}\n`;
+
+  let next;
+  let action;
+  let summary;
+  if (!existsSync(path)) {
+    next = latest;
+    action = 'create';
+    summary = 'a guide for AI helpers: the game contract and phone layout rules';
+  } else {
+    const current = readFileSync(path, 'utf8');
+    const start = current.indexOf(AGENTS_START);
+    const end = current.indexOf(AGENTS_END);
+    if (OUR_AGENTS.test(current)) {
+      if (current === latest) return null;
+      next = latest;
+      summary = 'replace with the latest guide for AI helpers';
+    } else if (start >= 0 && end > start) {
+      const tail = current.slice(end + AGENTS_END.length).replace(/^\n/, '');
+      next = current.slice(0, start) + section + tail;
+      if (next === current) return null;
+      summary = 'refresh the MyVillage section (your own text is kept)';
+    } else {
+      next = current.trimEnd() + '\n\n' + section;
+      summary = 'add a MyVillage section at the end (your own text is kept)';
+    }
+    action = 'update';
+  }
+  if (!dryRun) writeFileSync(path, next);
+  return { action, summary };
+}
+
+/**
+ * Make a Vite config use base: './'. Returns { text, summary } with the new
+ * config, { note } when it can't be changed safely (a computed base, a config
+ * shape we don't recognise), or {} when it's already right.
+ */
+export function withRelativeBase(config) {
+  const literal = /\bbase\s*:\s*(['"`])([^'"`]*)\1/.exec(config);
+  if (literal) {
+    if (literal[2] === './' || literal[2] === '') return {};
+    return {
+      text: config.slice(0, literal.index) + "base: './'" + config.slice(literal.index + literal[0].length),
+      summary: `use relative asset paths: base '${literal[2]}' becomes './'`,
+    };
+  }
+  if (/\bbase\s*:/.test(config)) {
+    return { note: "`base` is computed, so it was left alone. Make sure the build uses base: './' (relative asset paths); MyVillage serves the game from its own folder." };
+  }
+  const open = /(defineConfig\(\s*(?:\([^)]*\)\s*=>\s*\(\s*)?\{|export\s+default\s+\{|module\.exports\s*=\s*\{)/.exec(config);
+  if (!open) {
+    return { note: "couldn't find where to add base: './'. Add it to the config so asset paths are relative; MyVillage serves the game from its own folder." };
+  }
+  const at = open.index + open[0].length;
+  return {
+    text: config.slice(0, at) + "\n  base: './'," + config.slice(at),
+    summary: "use relative asset paths (base: './') so the game loads from MyVillage",
+  };
+}

package/src/utils/game-toolkit.js

@@ -1,4 +1,4 @@
-import { existsSync, readFileSync, writeFileSync, readdirSync, statSync } from 'fs';
+import { existsSync, readFileSync, writeFileSync, readdirSync, statSync, mkdirSync } from 'fs';
 import { join, dirname, extname } from 'path';
 import { fileURLToPath } from 'url';
 
@@ -28,9 +28,10 @@ const TOOLKIT_FILES = [
 
 /**
  * Bring a game's platform files up to the toolkit bundled with this CLI.
- * Returns the paths it changed. Does nothing for a game without our bridge.
+ * Returns the paths it changed (or, with `dryRun`, would change). Does nothing
+ * for a game without our bridge.
  */
-export function refreshGameToolkit(projectDir) {
+export function refreshGameToolkit(projectDir, { dryRun = false } = {}) {
   const bridge = join(projectDir, 'src/myvillage-game.js');
   if (!existsSync(bridge) || !TOOLKIT_FILES[0].isOurs(readFileSync(bridge, 'utf8'))) return [];
 
@@ -44,12 +45,39 @@ export function refreshGameToolkit(projectDir) {
     } else if (!file.createIfMissing) {
       continue;
     }
-    writeFileSync(target, latest);
+    if (!dryRun) writeFileSync(target, latest);
     changed.push(file.target);
   }
   return changed;
 }
 
+/**
+ * Add the toolkit to a game that doesn't have it yet (`init-game`). Never
+ * replaces a file of the same name that isn't ours; those come back in
+ * `conflicts` so the caller can say so.
+ */
+export function installGameToolkit(projectDir, { dryRun = false } = {}) {
+  const changed = [];
+  const conflicts = [];
+  for (const file of TOOLKIT_FILES) {
+    const target = join(projectDir, file.target);
+    if (existsSync(target)) {
+      if (!file.isOurs(readFileSync(target, 'utf8'))) conflicts.push(file.target);
+      continue;
+    }
+    if (!dryRun) {
+      mkdirSync(dirname(target), { recursive: true });
+      writeFileSync(target, readFileSync(file.source, 'utf8'));
+    }
+    changed.push(file.target);
+  }
+  // A bridge that was already there may be an older copy of ours.
+  if (!conflicts.includes(TOOLKIT_FILES[0].target)) {
+    changed.push(...refreshGameToolkit(projectDir, { dryRun }).filter((p) => !changed.includes(p)));
+  }
+  return { changed, conflicts };
+}
+
 /**
  * Whether the game's own code (not the toolkit) ever calls complete(). A game
  * that never does can't record a finished game or pay its reward.

package/src/utils/templates.js

@@ -700,20 +700,7 @@ function createNarrativeProject(targetDir, options) {
 function createArenaProject(targetDir, options) {
   const { name, description, ageGroup, orientation = 'landscape' } = options;
   const slug = name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/(^-|-$)/g, '');
-  const src = join(ASSETS_DIR, 'templates', 'arena');
-  const vars = {
-    NAME: name,
-    SLUG: slug,
-    DESCRIPTION: description || 'A real-time multiplayer arena game.',
-    ORIENTATION: orientation,
-    GOLD: BRAND.gold,
-    DARK: BRAND.darkBrown,
-    CONTAINER_CSS: orientation === 'portrait'
-      ? `#game-container { position: relative; width: 100vw; height: 100vh; height: 100dvh; overflow: hidden; }
-    @media (min-aspect-ratio: 3/4) { #game-container { width: min(100vw, calc(100dvh * 9 / 16)); margin: 0 auto; } }`
-      : '#game-container { position: relative; width: 100%; height: 100%; overflow: hidden; }',
-  };
-  const fill = (file) => readFileSync(join(src, file), 'utf8').replace(/\{\{([A-Z_]+)\}\}/g, (m, k) => (k in vars ? vars[k] : m));
+  const fill = arenaTemplateFiller(name, slug, description, orientation);
 
   for (const dir of ['', 'src', 'assets', 'public']) {
     mkdirSync(join(targetDir, dir), { recursive: true });
@@ -731,6 +718,24 @@ function createArenaProject(targetDir, options) {
   copyTemplateArt(targetDir, 'arena', orientation);
 }
 
+// Reads one arena template file with its {{VARS}} filled in.
+function arenaTemplateFiller(name, slug, description, orientation) {
+  const src = join(ASSETS_DIR, 'templates', 'arena');
+  const vars = {
+    NAME: name,
+    SLUG: slug,
+    DESCRIPTION: description || 'A real-time multiplayer arena game.',
+    ORIENTATION: orientation,
+    GOLD: BRAND.gold,
+    DARK: BRAND.darkBrown,
+    CONTAINER_CSS: orientation === 'portrait'
+      ? `#game-container { position: relative; width: 100vw; height: 100vh; height: 100dvh; overflow: hidden; }
+    @media (min-aspect-ratio: 3/4) { #game-container { width: min(100vw, calc(100dvh * 9 / 16)); margin: 0 auto; } }`
+      : '#game-container { position: relative; width: 100%; height: 100%; overflow: hidden; }',
+  };
+  return (file) => readFileSync(join(src, file), 'utf8').replace(/\{\{([A-Z_]+)\}\}/g, (m, k) => (k in vars ? vars[k] : m));
+}
+
 function generateArenaPackageJson(name, description, slug, ageGroup, orientation) {
   const pkg = JSON.parse(generatePackageJson(name, description || 'A real-time multiplayer arena game.', slug, 'arena', ageGroup, orientation));
   pkg.myvillage.category = 'action';
@@ -1154,7 +1159,7 @@ function generate2DGameAgents(name, gameType, orientation) {
     '',
     '## Conventions',
     '',
-    '- Orientation is **' + orientation + '** (set in `package.json` -> `myvillage.orientation`). Portrait runs on muni mobile **and** web; landscape is web-only.',
+    '- Orientation is **' + orientation + '** (set in `package.json` -> `myvillage.orientation`). Both play in the muni mobile app (it turns the phone to match) and on the web.',
     '- Vanilla JS, no framework — keep it dependency-light.',
     '',
   ].join('\n');
@@ -1248,12 +1253,108 @@ function generate3DGameAgents(name, type, orientation) {
     '',
     '## Conventions',
     '',
-    '- Orientation is **' + orientation + '** (`package.json` -> `myvillage.orientation`). Portrait runs on muni mobile **and** web; landscape is web-only.',
+    '- Orientation is **' + orientation + '** (`package.json` -> `myvillage.orientation`). Both play in the muni mobile app (it turns the phone to match) and on the web.',
     '- The follow-camera and game loop already exist — extend them, do not rebuild.',
     '',
   ].join('\n');
 }
 
+// For a web game that started outside MyVillage and was brought in with
+// `myvillage init-game`. We don't know its files, so instead of a file map it
+// says how to connect any game to the host.
+function generateConvertedGameAgents(name, orientation) {
+  const banner = orientation === 'portrait'
+    ? '9:16 (e.g. 1080x1920) for this portrait game'
+    : '16:9 (e.g. 1920x1080) for this landscape game';
+  return [
+    '# AGENTS.md — working on this MyVillage game with an AI agent',
+    '',
+    '**' + name + '** is a web game that was brought into MyVillage. It is built with `npm run build` and runs inside the MyVillage host (the muni mobile app or the web player) and standalone in a browser.',
+    '',
+    'When editing: make the requested change, keep the **MyVillage game contract** intact (see below), and keep `npm run build` working.',
+    '',
+    '## Platform files',
+    '',
+    '| File | Purpose |',
+    '|------|---------|',
+    '| `src/myvillage-game.js` | Host bridge — **do not edit.** Import it from the game\'s code: `import { MyVillageGame } from \'./myvillage-game.js\'` (path relative to the importing file). |',
+    '| `src/myvillage-realtime.js` | Multiplayer netcode (unused unless the game calls `MyVillageGame.multiplayer()`) — **do not edit.** |',
+    '| `assets/` | Cover art shipped on deploy. |',
+    '| `package.json` | The `myvillage` block holds metadata `myvillage deploy` reads. |',
+    '',
+    'Everything else is the game\'s own code. Read it before changing it, and keep its structure.',
+    '',
+    '## The MyVillage game contract — DO NOT BREAK',
+    '',
+    '- `MyVillageGame.ready()` — call once, when the game is interactive (after loading).',
+    '- `MyVillageGame.complete({ score, won })` — **required.** Call it on **every** way the game can end (win, lose, out of time, last level done). It records a completion and awards the player\'s reward. A game with no ending (endless, sandbox) needs a real one that fits it: a goal, a last level, a time limit.',
+    '- **Plays count automatically.** `src/myvillage-game.js` reports how long the player is actively playing; the platform counts a play after 30 seconds of it. Do not add timers, fake input, or early `complete()` calls to make plays count.',
+    '- Optional: `MyVillageGame.progress({ score })` reports the running score during play. It is throttled, so calling it every frame is fine.',
+    '',
+    'Do **not** add an Exit button — the host always provides its own. During `npm run dev` there is no host, so host calls just log to the console (expected).',
+    '',
+    '## Screen layout (phones)',
+    '',
+    '- The game fills the whole screen edge to edge, including behind the status bar and home indicator. The viewport meta needs `viewport-fit=cover`. Never letterbox it or add bars.',
+    '- Define the safe-area variables in `:root`: `--safe-top`, `--safe-bottom`, `--safe-left`, `--safe-right` as `max(env(safe-area-inset-*, 0px), var(--mv-safe-*, 0px))`, plus `--hud-top: calc(var(--safe-top) + 12px)` and `--exit-clear: 64px`. Keep HUD inside them: top row at `var(--hud-top)`, others offset by `var(--safe-bottom)` / `var(--safe-left)` / `var(--safe-right)`.',
+    '- Leave the **top-left corner** (`var(--exit-clear)` wide, below `var(--safe-top)`) empty: the host app draws its Exit button there. Put Pause and other top buttons on the right.',
+    '',
+    '## Run / build / deploy',
+    '',
+    '    npm install',
+    '    npm run dev      # local dev server, live reload',
+    '    npm run build    # production build -> dist/ (must pass before deploy)',
+    '    myvillage deploy # build, then upload + submit to MyVillage',
+    '',
+    'Keep asset URLs relative (Vite `base: \'./\'`). The host serves from a sub-path, so absolute `/...` URLs break.',
+    '',
+    '## Cover art (`assets/`)',
+    '',
+    '- `thumbnail.png` — square 1:1 (e.g. 512x512). The game card; required.',
+    '- `banner.png` — ' + banner + '. Featured hero; optional.',
+    '',
+    '## Conventions',
+    '',
+    '- Orientation is **' + orientation + '** (`package.json` -> `myvillage.orientation`). Both play in the muni mobile app (it turns the phone to match) and on the web.',
+    '- Don\'t add npm dependencies unless the change really needs one.',
+    '',
+  ].join('\n');
+}
+
+/**
+ * The AGENTS.md this CLI would write for a JS game, from its package.json
+ * `myvillage` block. Lets `init-game` bring an older game's guide up to date.
+ */
+export function generateGameAgents(myvillage, { slug, description } = {}) {
+  const name = myvillage.name || slug || 'My Game';
+  const orientation = myvillage.orientation === 'portrait' ? 'portrait' : 'landscape';
+  if (myvillage.converted) return generateConvertedGameAgents(name, orientation);
+  const type = String(myvillage.gameType || 'custom');
+  if (type === 'quiz' || type === 'narrative') return generate2DGameAgents(name, type, orientation);
+  if (type === 'arena' || myvillage.multiplayer) {
+    const gameSlug = slug || name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/(^-|-$)/g, '');
+    return arenaTemplateFiller(name, gameSlug, description, orientation)('AGENTS.md');
+  }
+  return generate3DGameAgents(name, type, orientation);
+}
+
+/** Vite config for a converted game that had none: just the relative base. */
+export function generateMinimalViteConfig() {
+  return `import { defineConfig } from 'vite';
+
+// base: './' keeps asset URLs relative. MyVillage serves each game from its own
+// folder (/api/v1/games/game-files/<slug>/), so absolute /assets/... URLs break.
+export default defineConfig({
+  base: './',
+});
+`;
+}
+
+/** Bundled starter thumbnail (square) for a game that has no cover art yet. */
+export function starterThumbnailPath() {
+  return join(GAME_ART_DIR, 'custom-thumbnail.png');
+}
+
 function generateUnityAgents(name, className, orientation) {
   const isLandscape = orientation === 'landscape';
   const reach = isLandscape
@@ -1740,8 +1841,8 @@ function generatePackageJson(name, description, slug, type, ageGroup, orientatio
       gameId: null,
       gameType: type,
       targetAge: ageGroup,
-      // Portrait games run in the muni mobile app AND on the web (mvp-video-games).
-      // Landscape games run on the web only. Hosts read this to frame the game.
+      // Both orientations run in the muni mobile app (it rotates to match) and on
+      // the web (mvp-video-games). Hosts read this to frame the game.
       orientation,
       aspectRatio: orientation === 'portrait' ? '9:16' : '16:9',
       // Declared up front so `myvillage deploy` ships them with the submission.