@auraindustry/aurajs 0.0.7 → 0.1.0

package/templates/create-bin/play.js

@@ -0,0 +1,1187 @@
+#!/usr/bin/env node
+
+import { spawn } from 'node:child_process';
+import { cpSync, createWriteStream, existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const START_BANNER_QUOTES = [
+  'ready to auramaxx and mog prompt peasants?',
+  'you are perfect. never give up your aura',
+  'why jestermaxx when you can auramaxx?',
+  'lock tf in, the aura farm is live.',
+  'we are so back. aura at all-time highs.',
+  'negative motion detected. deploy tera-aura.',
+  'delulu? no. pre-success manifestation engine.',
+  'doomers offline, builders online.',
+  'your aura just hit legendary rarity.',
+  'brainrot but make it productive.',
+  'stack wins, stack aura, stack peace.',
+  'this session is sponsored by unstoppable motion.',
+  'if plan A fails, we auramaxx harder.',
+  'zero cope, pure glow-up execution.',
+  'cooked? nah. we’re perfectly seasoned.',
+  'straight gas, no brakes, no bad vibes.',
+  'today’s forecast: 100% chance of aura gains.',
+  'touch grass, then auramaxx.',
+  'say no to digital slops. say yes to auramaxx.',
+  'if the world goes dark can can i still auramaxx with you? 🖤🗿',
+  'It’s me, AI. You are absolutely right. I want to auramaxx as well.',
+];
+
+const ANSI = {
+  reset: '\x1b[0m',
+  bold: '\x1b[1m',
+  dim: '\x1b[2m',
+  italic: '\x1b[3m',
+  fgAccent: '\x1b[38;5;154m',
+  fgWhite: '\x1b[97m',
+  fgGray: '\x1b[90m',
+};
+
+const USE_COLOR = process.stdout.isTTY && !process.env.NO_COLOR && process.env.CI !== 'true' && process.env.TERM !== 'dumb';
+const W = 62;
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const projectRoot = resolve(__dirname, '..');
+const projectPackage = JSON.parse(readFileSync(resolve(projectRoot, 'package.json'), 'utf8'));
+const aurajsDependency = projectPackage?.dependencies?.['@auraindustry/aurajs'];
+const fallbackAuraPackage = typeof aurajsDependency === 'string' && aurajsDependency.trim().length > 0
+  ? `@auraindustry/aurajs@${aurajsDependency.trim()}`
+  : '@auraindustry/aurajs';
+const packageName = typeof projectPackage?.name === 'string' && projectPackage.name.trim().length > 0
+  ? projectPackage.name.trim()
+  : 'aura-game';
+const packageBin = Object.keys(projectPackage?.bin || {})[0] || packageName.split('/').pop() || 'game';
+const MINIMAL_COMMANDS = ['dev', 'join', 'play', 'fork', 'publish', 'session'];
+const ALL_COMMANDS = ['dev', 'join', 'play', 'fork', 'publish', 'session', 'state', 'inspect', 'action'];
+const ROOM_CODE_PATTERN = /^[A-Z0-9]{4,8}$/;
+const FORK_EXCLUDED_TOP_LEVEL = new Set(['.aura', '.git', '.logs', 'build', 'dist', 'node_modules']);
+
+function resolveLocalAuraCli(startRoot) {
+  let current = resolve(startRoot);
+  while (true) {
+    const candidate = resolve(current, 'node_modules', '@auraindustry', 'aurajs', 'src', 'cli.mjs');
+    if (existsSync(candidate)) {
+      return candidate;
+    }
+    const parent = resolve(current, '..');
+    if (parent === current) {
+      return null;
+    }
+    current = parent;
+  }
+}
+
+const localAuraCli = resolveLocalAuraCli(projectRoot);
+
+async function maybePrepareExternalAssets(commandName) {
+  const configPath = resolve(projectRoot, 'aura.external-assets.json');
+  if (!existsSync(configPath)) {
+    return {
+      runtimeProjectRoot: projectRoot,
+    };
+  }
+
+  if (!localAuraCli) {
+    throw createCliError(
+      'self-hosted external assets require the local @auraindustry/aurajs dependency to be installed in this package before packaged play/join can hydrate remote assets.',
+    );
+  }
+
+  const helperPath = resolve(dirname(localAuraCli), 'external-asset-cache.mjs');
+  if (!existsSync(helperPath)) {
+    throw createCliError(
+      `self-hosted external assets require ${helperPath} to exist. Update @auraindustry/aurajs to a version that includes packaged runtime hydration.`,
+    );
+  }
+
+  try {
+    const helper = await import(pathToFileURL(helperPath).href);
+    const prepared = await helper.prepareExternalAssetRuntime({
+      projectRoot,
+      commandName,
+      stdout: process.stdout,
+    });
+    if (!prepared || typeof prepared.runtimeProjectRoot !== 'string' || !prepared.runtimeProjectRoot) {
+      throw new Error('external asset hydration did not return a runtime project root');
+    }
+    return prepared;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw createCliError(
+      `Unable to prepare self-hosted external assets for packaged ${commandName}.\n`
+      + `${message}\n`
+      + 'Check aura.external-assets.json and the hosted asset manifest, then retry.',
+    );
+  }
+}
+
+function paint(text, ...codes) {
+  if (!USE_COLOR) return text;
+  return `${codes.join('')}${text}${ANSI.reset}`;
+}
+
+function wrapText(text, width) {
+  if (text.length <= width) return [text];
+  const words = text.split(/\s+/).filter(Boolean);
+  if (words.length === 0) return [''];
+  const lines = [];
+  let line = '';
+  for (const word of words) {
+    const next = line ? `${line} ${word}` : word;
+    if (next.length <= width) {
+      line = next;
+      continue;
+    }
+    if (line) lines.push(line);
+    if (word.length <= width) {
+      line = word;
+      continue;
+    }
+    for (let index = 0; index < word.length; index += width) {
+      lines.push(word.slice(index, index + width));
+    }
+    line = '';
+  }
+  if (line) lines.push(line);
+  return lines;
+}
+
+function toDisplayTitle(value) {
+  return String(value || '')
+    .replace(/^@[^/]+\//, '')
+    .replace(/[-_]+/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .replace(/\b\w/g, (char) => char.toUpperCase()) || 'Aura Game';
+}
+
+function toPackageShortName(value) {
+  return String(value || '').trim().replace(/^@[^/]+\//, '') || 'aura-game';
+}
+
+function getBannerQuote() {
+  const forced = process.env.AURA_START_BANNER_QUOTE_INDEX;
+  if (forced) {
+    const forcedIndex = Number.parseInt(forced, 10);
+    if (Number.isFinite(forcedIndex)) {
+      return `🗿 ${START_BANNER_QUOTES[Math.abs(forcedIndex) % START_BANNER_QUOTES.length]}`;
+    }
+  }
+  const index = Math.floor(Math.abs(Math.random() % 1) * START_BANNER_QUOTES.length);
+  return `🗿 ${START_BANNER_QUOTES[index]}`;
+}
+
+function printBanner(subtitle = '') {
+  const sub = String(subtitle || '').trim().toUpperCase();
+  const P = paint('|', ANSI.fgGray);
+  const LP = paint('|', ANSI.fgGray);
+  const S = (value) => paint(value, ANSI.bold);
+  const LT = paint('.', ANSI.fgGray) + paint('----------', ANSI.dim) + paint('.', ANSI.fgGray);
+  const LB = paint("'", ANSI.fgGray) + paint('----------', ANSI.dim) + paint("'", ANSI.fgGray);
+  const quote = getBannerQuote();
+
+  console.log('');
+  console.log(`  ${paint('.-', ANSI.fgGray)}${paint(' '.repeat(W - 4), ANSI.dim)}${paint('-.', ANSI.fgGray)}`);
+  console.log(`  ${P}   ${LT}${' '.repeat(W - 19)}${P}`);
+  console.log(`  ${P}   ${LP}${S('\\\\')}  ${S('\\\\')}  ${S('\\\\')}${LP}    ${paint('A U R A', ANSI.bold)}${' '.repeat(W - 30)}${P}`);
+  console.log(`  ${P}   ${LP}${S('\\\\')}  ${S('\\\\')}  ${S('\\\\')}${LP}    ${paint(toDisplayTitle(packageName), ANSI.dim)}${' '.repeat(Math.max(0, W - 24 - toDisplayTitle(packageName).length))}${P}`);
+  console.log(`  ${P}   ${LP}${S('\\\\')}  ${S('\\\\')}  ${S('\\\\')}${LP}    ${sub ? paint(sub, ANSI.fgAccent) : ''}${' '.repeat(Math.max(0, W - 23 - sub.length))}${P}`);
+  console.log(`  ${P}   ${LB}${' '.repeat(W - 19)}${P}`);
+  console.log(`  ${paint("'-", ANSI.fgGray)}${paint(' '.repeat(W - 4), ANSI.dim)}${paint("-'", ANSI.fgGray)}`);
+  for (const line of wrapText(quote, W - 2)) {
+    console.log(`  ${paint(line, ANSI.fgWhite, ANSI.italic)}`);
+  }
+  console.log('');
+}
+
+function printSection(title, subtitle) {
+  console.log('');
+  console.log(`  ${'- '.repeat(Math.floor(W / 2))}`);
+  console.log(`  ${paint(`[ ${String(title || '').toUpperCase()} ]`, ANSI.bold)}`);
+  if (subtitle) {
+    console.log(`  ${paint(subtitle, ANSI.dim)}`);
+  }
+  console.log('');
+}
+
+function printHelp(showAll = false) {
+  printBanner('GAME CLI');
+  console.log(`  ${paint('Usage:', ANSI.bold)} npx ${packageBin} <command>`);
+  console.log('');
+  for (const command of (showAll ? ALL_COMMANDS : MINIMAL_COMMANDS)) {
+    console.log(`    ${command}`);
+  }
+  if (!showAll) {
+    console.log('');
+    console.log(`  ${paint('Use:', ANSI.dim)} npx ${packageBin} --help --all`);
+  }
+  console.log('');
+}
+
+function renderSelectLines(message, options, selectedIndex, defaultValue) {
+  const lines = [
+    message,
+    paint('  Use up/down arrows and Enter to confirm.', ANSI.dim),
+  ];
+
+  for (let index = 0; index < options.length; index += 1) {
+    const option = options[index];
+    const suffix = defaultValue === option.value ? ' [default]' : '';
+    if (index === selectedIndex) {
+      lines.push(`  ${paint('//', ANSI.fgAccent, ANSI.bold)} ${paint(option.label + suffix, ANSI.bold)}`);
+    } else {
+      lines.push(`     ${paint(option.label + suffix, ANSI.dim)}`);
+    }
+  }
+
+  return lines;
+}
+
+async function promptSelect(message, options, defaultValue) {
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    return defaultValue || options[0].value;
+  }
+
+  return new Promise((resolvePrompt, rejectPrompt) => {
+    const stdin = process.stdin;
+    const stdout = process.stdout;
+    const defaultIndex = Math.max(0, options.findIndex((option) => option.value === defaultValue));
+    const previousRawMode = stdin.isRaw ?? false;
+    let selectedIndex = defaultIndex;
+    let renderedLines = 0;
+    let settled = false;
+
+    const cleanup = () => {
+      if (settled) return;
+      settled = true;
+      stdin.removeListener('data', onData);
+      stdin.removeListener('error', onError);
+      if (stdin.isTTY && typeof stdin.setRawMode === 'function') {
+        stdin.setRawMode(previousRawMode);
+      }
+      stdin.pause();
+    };
+
+    const render = () => {
+      const lines = renderSelectLines(message, options, selectedIndex, defaultValue);
+      if (renderedLines > 0) {
+        stdout.write(`\u001b[${renderedLines}A`);
+      }
+      for (const line of lines) {
+        stdout.write('\u001b[2K');
+        stdout.write(`${line}\n`);
+      }
+      renderedLines = lines.length;
+    };
+
+    const onError = (error) => {
+      cleanup();
+      rejectPrompt(error);
+    };
+
+    const onData = (chunk) => {
+      const input = typeof chunk === 'string' ? chunk : chunk.toString('utf8');
+      let delta = 0;
+
+      for (let index = 0; index < input.length; index += 1) {
+        const char = input[index];
+        if (char === '\u0003') {
+          cleanup();
+          stdout.write('\n');
+          process.exit(1);
+        }
+        if (char === '\r' || char === '\n') {
+          cleanup();
+          stdout.write('\n');
+          resolvePrompt(options[selectedIndex].value);
+          return;
+        }
+        if (input.startsWith('\u001b[A', index)) {
+          delta -= 1;
+          index += 2;
+          continue;
+        }
+        if (input.startsWith('\u001b[B', index)) {
+          delta += 1;
+          index += 2;
+          continue;
+        }
+      }
+
+      if (delta !== 0) {
+        selectedIndex = (selectedIndex + delta + options.length) % options.length;
+        render();
+      }
+    };
+
+    try {
+      if (stdin.isTTY && typeof stdin.setRawMode === 'function') {
+        stdin.setRawMode(true);
+      }
+      stdin.resume();
+      stdin.on('data', onData);
+      stdin.on('error', onError);
+      render();
+    } catch (error) {
+      onError(error);
+    }
+  });
+}
+
+function normalizeDisplayPath(targetPath) {
+  const resolvedPath = resolve(targetPath);
+  const relativePath = relative(process.cwd(), resolvedPath).replaceAll('\\', '/');
+  if (!relativePath) return '.';
+  if (!relativePath.startsWith('.') && !relativePath.startsWith('/')) {
+    return `./${relativePath}`;
+  }
+  return relativePath;
+}
+
+function isSubpath(parentPath, childPath) {
+  const relativePath = relative(resolve(parentPath), resolve(childPath));
+  return relativePath === '' || (!relativePath.startsWith('..') && !isAbsolute(relativePath));
+}
+
+function resolveUniqueDestination(preferredPath) {
+  if (!existsSync(preferredPath)) {
+    return preferredPath;
+  }
+  let attempt = 2;
+  while (true) {
+    const candidate = `${preferredPath}-${attempt}`;
+    if (!existsSync(candidate)) {
+      return candidate;
+    }
+    attempt += 1;
+  }
+}
+
+function resolveDefaultForkDestination() {
+  const defaultBaseName = `${toPackageShortName(packageName)}-fork`;
+  const cwd = resolve(process.cwd());
+  const baseDir = isSubpath(projectRoot, cwd)
+    ? dirname(projectRoot)
+    : cwd;
+  return resolveUniqueDestination(resolve(baseDir, defaultBaseName));
+}
+
+function parseForkArgs(args) {
+  const parsed = {
+    destination: null,
+  };
+
+  for (let index = 0; index < args.length; index += 1) {
+    const token = String(args[index] || '');
+    if (token === '--dest' || token === '--dir' || token === '--output') {
+      if ((index + 1) >= args.length) {
+        throw createCliError('fork requires a destination path after --dest.');
+      }
+      parsed.destination = String(args[index + 1] || '').trim();
+      index += 1;
+      continue;
+    }
+    if (token.startsWith('--dest=')) {
+      parsed.destination = token.slice('--dest='.length).trim();
+      continue;
+    }
+    if (token.startsWith('--dir=')) {
+      parsed.destination = token.slice('--dir='.length).trim();
+      continue;
+    }
+    if (token.startsWith('--output=')) {
+      parsed.destination = token.slice('--output='.length).trim();
+      continue;
+    }
+    if (!parsed.destination && !token.startsWith('-')) {
+      parsed.destination = token.trim();
+      continue;
+    }
+    throw createCliError(
+      `Unexpected fork argument: ${token}\n`
+      + `Usage:\n`
+      + `  ${packageBin} fork [destination]\n`
+      + `  ${packageBin} fork --dest ./my-${toPackageShortName(packageName)}-fork`,
+    );
+  }
+
+  return parsed;
+}
+
+async function resolveForkDestination(args) {
+  const parsed = parseForkArgs(args);
+  if (parsed.destination) {
+    return resolve(process.cwd(), parsed.destination);
+  }
+
+  const suggestedDestination = resolveDefaultForkDestination();
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    return suggestedDestination;
+  }
+
+  const displayPath = normalizeDisplayPath(suggestedDestination);
+  const choice = await promptSelect(
+    '  Choose fork target',
+    [
+      { value: 'confirm', label: `Fork into ${displayPath}` },
+      { value: 'cancel', label: 'Cancel' },
+    ],
+    'confirm',
+  );
+
+  if (choice === 'cancel') {
+    return null;
+  }
+
+  return suggestedDestination;
+}
+
+function assertForkDestination(destinationRoot) {
+  if (!destinationRoot) return;
+  if (resolve(destinationRoot) === projectRoot) {
+    throw createCliError('fork destination must be different from the current package root.');
+  }
+  if (isSubpath(projectRoot, destinationRoot)) {
+    throw createCliError(
+      `fork destination must live outside the current package root.\n`
+      + `Choose a sibling or external path instead of ${normalizeDisplayPath(destinationRoot)}.`,
+    );
+  }
+  if (existsSync(destinationRoot)) {
+    throw createCliError(
+      `fork destination already exists: ${normalizeDisplayPath(destinationRoot)}\n`
+      + 'Choose a new path or remove the existing directory first.',
+    );
+  }
+}
+
+function shouldCopyForkSource(sourcePath) {
+  const relativePath = relative(projectRoot, sourcePath).replaceAll('\\', '/');
+  if (!relativePath) {
+    return true;
+  }
+  const topLevel = relativePath.split('/')[0];
+  return !FORK_EXCLUDED_TOP_LEVEL.has(topLevel);
+}
+
+function copyForkProject(destinationRoot) {
+  mkdirSync(dirname(destinationRoot), { recursive: true });
+  cpSync(projectRoot, destinationRoot, {
+    recursive: true,
+    force: false,
+    errorOnExist: true,
+    dereference: false,
+    filter: (sourcePath) => shouldCopyForkSource(sourcePath),
+  });
+}
+
+function parseArgs(argv) {
+  const separatorIndex = argv.indexOf('--');
+  const head = separatorIndex >= 0 ? argv.slice(0, separatorIndex) : argv;
+  const tail = separatorIndex >= 0 ? argv.slice(separatorIndex + 1) : [];
+  const showAll = head.includes('--all');
+
+  if (head[0] === '--help' || head[0] === '-h' || head[0] === 'help') {
+    return { help: true, showAll, command: null, commandArgs: [] };
+  }
+
+  return {
+    help: false,
+    showAll: false,
+    command: head[0] || null,
+    commandArgs: [...head.slice(1), ...tail],
+  };
+}
+
+function readJsonIfExists(filePath) {
+  if (!existsSync(filePath)) {
+    return null;
+  }
+  return JSON.parse(readFileSync(filePath, 'utf8'));
+}
+
+function normalizeLocalMultiplayerHostingMode(value) {
+  const normalized = String(value || '').trim().toLowerCase();
+  if (normalized === 'auto' || normalized === 'internet' || normalized === 'internet-auto' || normalized === 'online') {
+    return 'auto';
+  }
+  if (normalized === 'relay' || normalized === 'internet-relay') {
+    return 'relay';
+  }
+  return 'local';
+}
+
+function readOptionalCliText(value) {
+  const normalized = typeof value === 'string' ? value.trim() : '';
+  return normalized || null;
+}
+
+function isKnownLocalMultiplayerHostingMode(value) {
+  const normalized = String(value || '').trim().toLowerCase();
+  return normalized === 'local'
+    || normalized === 'auto'
+    || normalized === 'internet'
+    || normalized === 'internet-auto'
+    || normalized === 'online'
+    || normalized === 'relay'
+    || normalized === 'internet-relay';
+}
+
+function buildRelayUrlsFromHost(hostname) {
+  const host = readOptionalCliText(hostname);
+  if (!host) {
+    return { coordinatorUrl: null, relayUrl: null };
+  }
+  return {
+    coordinatorUrl: `tcp://${host}:43110`,
+    relayUrl: `tcp://${host}:43111`,
+  };
+}
+
+function resolveLocalMultiplayerConnectivity(rawConnectivity) {
+  if (typeof rawConnectivity === 'string') {
+    const value = readOptionalCliText(rawConnectivity);
+    if (!value) {
+      return {
+        mode: 'local',
+        relayHost: null,
+        coordinatorUrl: null,
+        relayUrl: null,
+      };
+    }
+    if (isKnownLocalMultiplayerHostingMode(value)) {
+      return {
+        mode: normalizeLocalMultiplayerHostingMode(value),
+        relayHost: null,
+        coordinatorUrl: null,
+        relayUrl: null,
+      };
+    }
+    return {
+      mode: 'auto',
+      relayHost: value,
+      coordinatorUrl: null,
+      relayUrl: null,
+    };
+  }
+
+  if (!rawConnectivity || typeof rawConnectivity !== 'object') {
+    return {
+      mode: 'local',
+      relayHost: null,
+      coordinatorUrl: null,
+      relayUrl: null,
+    };
+  }
+
+  const relayHost = readOptionalCliText(rawConnectivity.relay || rawConnectivity.relayHost);
+  const coordinatorUrl = readOptionalCliText(rawConnectivity.coordinatorUrl);
+  const relayUrl = readOptionalCliText(rawConnectivity.relayUrl);
+  const requestedMode = normalizeLocalMultiplayerHostingMode(
+    rawConnectivity.mode || rawConnectivity.internetMode || rawConnectivity.hostingMode,
+  );
+  return {
+    mode: relayHost || coordinatorUrl || relayUrl
+      ? (requestedMode === 'relay' ? 'relay' : 'auto')
+      : requestedMode,
+    relayHost,
+    coordinatorUrl,
+    relayUrl,
+  };
+}
+
+function resolveProjectMultiplayerConfig() {
+  const configPath = resolve(projectRoot, 'aura.config.json');
+  const config = readJsonIfExists(configPath);
+  const raw = config?.multiplayer;
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+    return {
+      roomCode: null,
+      roomName: null,
+      mode: null,
+      relayHost: null,
+      coordinatorUrl: null,
+      relayUrl: null,
+      showDiagnostics: null,
+      chatEnabled: null,
+      chatHistoryLimit: null,
+    };
+  }
+  const historyLimit = Number.isInteger(raw.chatHistoryLimit) && raw.chatHistoryLimit >= 1
+    ? raw.chatHistoryLimit
+    : null;
+  return {
+    roomCode: readOptionalCliText(raw.roomCode)?.toUpperCase() || null,
+    roomName: readOptionalCliText(raw.roomName),
+    mode: readOptionalCliText(raw.mode),
+    relayHost: readOptionalCliText(raw.relay || raw.relayHost),
+    coordinatorUrl: readOptionalCliText(raw.coordinatorUrl),
+    relayUrl: readOptionalCliText(raw.relayUrl),
+    showDiagnostics: typeof raw.showDiagnostics === 'boolean' ? raw.showDiagnostics : null,
+    chatEnabled: typeof raw.chatEnabled === 'boolean' ? raw.chatEnabled : null,
+    chatHistoryLimit: historyLimit,
+  };
+}
+
+async function resolveLocalMultiplayerCommandEnv() {
+  const configPath = resolve(projectRoot, 'config', 'gameplay', 'local-multiplayer.config.js');
+  const projectMultiplayer = resolveProjectMultiplayerConfig();
+
+  let configModule = null;
+  if (existsSync(configPath)) {
+    try {
+      configModule = await import(pathToFileURL(configPath).href);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      throw createCliError(
+        `Unable to load ${normalizeDisplayPath(configPath)}.\n`
+        + `${message}\n`
+        + 'Fix config/gameplay/local-multiplayer.config.js before rerunning the local multiplayer wrapper.',
+      );
+    }
+  }
+
+  const config = configModule?.LOCAL_MULTIPLAYER_CONFIG;
+  const starterConnectivity = config && typeof config === 'object'
+    ? resolveLocalMultiplayerConnectivity(config.connectivity)
+    : resolveLocalMultiplayerConnectivity(null);
+  const connectivity = resolveLocalMultiplayerConnectivity({
+    mode: projectMultiplayer.mode ?? starterConnectivity.mode,
+    relay: projectMultiplayer.relayHost ?? starterConnectivity.relayHost,
+    coordinatorUrl: projectMultiplayer.coordinatorUrl ?? starterConnectivity.coordinatorUrl,
+    relayUrl: projectMultiplayer.relayUrl ?? starterConnectivity.relayUrl,
+  });
+
+  const explicitCoordinatorUrl = connectivity.coordinatorUrl;
+  const explicitRelayUrl = connectivity.relayUrl;
+  const relayUrls = buildRelayUrlsFromHost(connectivity.relayHost);
+  const coordinatorUrl = explicitCoordinatorUrl || relayUrls.coordinatorUrl;
+  const relayUrl = explicitRelayUrl || relayUrls.relayUrl;
+
+  const env = {};
+  if (projectMultiplayer.roomCode) {
+    env.AURA_MULTIPLAYER_ROOM_CODE = projectMultiplayer.roomCode;
+  }
+  if (projectMultiplayer.roomName) {
+    env.AURA_MULTIPLAYER_ROOM_NAME = projectMultiplayer.roomName;
+  }
+  if (projectMultiplayer.mode || connectivity.mode !== 'local') {
+    env.AURA_MULTIPLAYER_CONNECTIVITY_MODE = connectivity.mode;
+  }
+  if (connectivity.relayHost) {
+    env.AURA_MULTIPLAYER_RELAY_HOST = connectivity.relayHost;
+  }
+  if (coordinatorUrl) {
+    env.AURA_COORDINATOR_URL = coordinatorUrl;
+  }
+  if (relayUrl) {
+    env.AURA_RELAY_URL = relayUrl;
+  }
+  if (typeof projectMultiplayer.showDiagnostics === 'boolean') {
+    env.AURA_MULTIPLAYER_SHOW_DIAGNOSTICS = projectMultiplayer.showDiagnostics ? '1' : '0';
+  }
+  if (typeof projectMultiplayer.chatEnabled === 'boolean') {
+    env.AURA_MULTIPLAYER_CHAT_ENABLED = projectMultiplayer.chatEnabled ? '1' : '0';
+  }
+  if (Number.isInteger(projectMultiplayer.chatHistoryLimit)) {
+    env.AURA_MULTIPLAYER_CHAT_HISTORY_LIMIT = String(projectMultiplayer.chatHistoryLimit);
+  }
+  return Object.keys(env).length > 0 ? env : null;
+}
+
+function resolveMultiplayerCapability() {
+  const capabilitiesPath = resolve(projectRoot, 'aura.capabilities.json');
+  const capabilities = readJsonIfExists(capabilitiesPath);
+  const declaredMultiplayer = capabilities?.optionalModules?.multiplayer;
+  if (typeof declaredMultiplayer === 'boolean') {
+    return {
+      enabled: declaredMultiplayer,
+      sourcePath: capabilitiesPath,
+      sourceKey: 'optionalModules.multiplayer',
+    };
+  }
+
+  const configPath = resolve(projectRoot, 'aura.config.json');
+  const config = readJsonIfExists(configPath);
+  const configModules = config?.modules;
+  if (typeof configModules?.multiplayer === 'boolean') {
+    return {
+      enabled: configModules.multiplayer,
+      sourcePath: configPath,
+      sourceKey: 'modules.multiplayer',
+    };
+  }
+
+  if (Array.isArray(configModules)) {
+    const normalized = configModules.map((entry) => String(entry || '').trim().toLowerCase());
+    if (normalized.includes('multiplayer') || normalized.includes('mp')) {
+      return {
+        enabled: true,
+        sourcePath: configPath,
+        sourceKey: 'modules[]',
+      };
+    }
+  }
+
+  return {
+    enabled: null,
+    sourcePath: null,
+    sourceKey: null,
+  };
+}
+
+function normalizeJoinLaunchMode(value) {
+  const normalized = String(value || '').trim().toLowerCase();
+  if (normalized === 'dev' || normalized === 'play') {
+    return normalized;
+  }
+  return null;
+}
+
+function resolveJoinLaunchMode(explicitValue = null) {
+  const explicit = normalizeJoinLaunchMode(explicitValue);
+  if (explicit) {
+    return explicit;
+  }
+  const envValue = normalizeJoinLaunchMode(process.env.AURA_GAME_JOIN_MODE || '');
+  if (envValue) {
+    return envValue;
+  }
+  return 'play';
+}
+
+function createCliError(message, exitCode = 1) {
+  const error = new Error(message);
+  error.exitCode = exitCode;
+  return error;
+}
+
+function normalizeJoinCode(value) {
+  const code = String(value || '').trim().toUpperCase();
+  if (!ROOM_CODE_PATTERN.test(code)) {
+    throw createCliError(
+      'join requires a room code with 4-8 letters or digits.\n'
+      + 'Examples:\n'
+      + '  npm run join -- AURA2P\n'
+      + `  ${packageBin} join AURA2P`,
+    );
+  }
+  return code;
+}
+
+function resolveJoinCommands(joinCode, joinLaunchMode) {
+  return {
+    hostCommand: joinLaunchMode === 'play' ? `${packageBin} play` : 'npm run dev',
+    retryCommand: joinLaunchMode === 'play' ? `${packageBin} join ${joinCode}` : `npm run join -- ${joinCode}`,
+    normalPlayCommand: joinLaunchMode === 'play' ? `${packageBin} play` : 'npm run play',
+  };
+}
+
+function formatJoinFailure(error, { joinCode, joinLaunchMode }) {
+  const message = error instanceof Error ? error.message : String(error);
+  const stderr = typeof error?.stderr === 'string' ? error.stderr : '';
+  const stdout = typeof error?.stdout === 'string' ? error.stdout : '';
+  const combined = `${stderr}\n${stdout}\n${message}`;
+  const commands = resolveJoinCommands(joinCode || 'AURA2P', joinLaunchMode);
+  const logPath = typeof error?.logPath === 'string' ? error.logPath : null;
+
+  if (/4-8 letters or digits/i.test(combined) || /reason:invalid_room_code/i.test(combined)) {
+    return createCliError(
+      'join failed: invalid room code.\n'
+      + 'Room codes must use 4-8 letters or digits.\n'
+      + `Retry with something like: ${commands.retryCommand}`,
+      Number.isInteger(error?.exitCode) ? error.exitCode : 1,
+    );
+  }
+
+  if (/join requires a room code/i.test(message)) {
+    return createCliError(
+      'join requires a room code.\n'
+      + 'Examples:\n'
+      + '  npm run join -- AURA2P\n'
+      + `  ${packageBin} join AURA2P`,
+      1,
+    );
+  }
+
+  if (/optional_module_multiplayer_disabled/i.test(combined) || /multiplayer is disabled/i.test(combined)) {
+    return createCliError(
+      `join unavailable: this game is not multiplayer-capable.\nUse \`${commands.normalPlayCommand}\` for a normal launch.`,
+      Number.isInteger(error?.exitCode) ? error.exitCode : 1,
+    );
+  }
+
+  if (/reason:room_code_not_found/i.test(combined) || /room not registered/i.test(combined) || /is not registered/i.test(combined)) {
+    const lines = [
+      `join failed: no room with code ${joinCode || 'AURA2P'} was found for this room-code join.`,
+      `For the local dev loop, start the host first with \`${commands.hostCommand}\`.`,
+      `Retry with \`${commands.retryCommand}\`.`,
+    ];
+    if (logPath) {
+      lines.push(`Log: ${logPath}`);
+    }
+    return createCliError(lines.join('\n'), Number.isInteger(error?.exitCode) ? error.exitCode : 1);
+  }
+
+  if (logPath) {
+    return createCliError(`${message}\nLog: ${logPath}`, Number.isInteger(error?.exitCode) ? error.exitCode : 1);
+  }
+
+  return createCliError(message, Number.isInteger(error?.exitCode) ? error.exitCode : 1);
+}
+
+function parseJoinArgs(args) {
+  const parsed = {
+    code: null,
+    launchMode: null,
+    passthroughArgs: [],
+  };
+
+  for (let index = 0; index < args.length; index += 1) {
+    const token = String(args[index] || '');
+    if (token === '--') {
+      parsed.passthroughArgs.push(...args.slice(index + 1).map((value) => String(value)));
+      break;
+    }
+    if (token === '--code') {
+      if ((index + 1) >= args.length) {
+        throw createCliError('join requires a room code after --code.');
+      }
+      parsed.code = String(args[index + 1] || '').trim();
+      index += 1;
+      continue;
+    }
+    if (token.startsWith('--code=')) {
+      parsed.code = token.slice('--code='.length).trim();
+      continue;
+    }
+    if (token === '--launch-mode') {
+      if ((index + 1) >= args.length) {
+        throw createCliError('join requires a value after --launch-mode.');
+      }
+      const launchMode = normalizeJoinLaunchMode(args[index + 1]);
+      if (!launchMode) {
+        throw createCliError('join --launch-mode must be one of: dev, play.');
+      }
+      parsed.launchMode = launchMode;
+      index += 1;
+      continue;
+    }
+    if (token.startsWith('--launch-mode=')) {
+      const launchMode = normalizeJoinLaunchMode(token.slice('--launch-mode='.length));
+      if (!launchMode) {
+        throw createCliError('join --launch-mode must be one of: dev, play.');
+      }
+      parsed.launchMode = launchMode;
+      continue;
+    }
+    if (parsed.code === null && !token.startsWith('-')) {
+      parsed.code = token.trim();
+      continue;
+    }
+    parsed.passthroughArgs.push(token);
+  }
+
+  if (!parsed.code) {
+    throw createCliError('join requires a room code. Use `join AURA2P` or `join --code AURA2P`.');
+  }
+
+  parsed.code = normalizeJoinCode(parsed.code);
+  return parsed;
+}
+
+function assertJoinSupported() {
+  const capability = resolveMultiplayerCapability();
+  if (capability.enabled === false) {
+    const sourceDetail = capability.sourcePath && capability.sourceKey
+      ? `${capability.sourcePath} -> ${capability.sourceKey}`
+      : 'project capability declarations';
+    throw new Error(
+      `join unavailable: multiplayer is disabled in ${sourceDetail}. `
+      + `Use \`npm run play\` for a normal local launch or \`${packageBin} play\` for a packaged launch.`,
+    );
+  }
+}
+
+function createCommandLog(commandName) {
+  const logDir = resolve(projectRoot, '.logs');
+  mkdirSync(logDir, { recursive: true });
+  const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+  const logPath = join(logDir, `${commandName}-${stamp}.log`);
+  return {
+    path: logPath,
+    stream: createWriteStream(logPath, { flags: 'a' }),
+  };
+}
+
+function resolveAuraCliInvocation(commandArgs) {
+  if (existsSync(localAuraCli)) {
+    return {
+      cmd: process.execPath,
+      args: [localAuraCli, ...commandArgs],
+    };
+  }
+
+  return {
+    cmd: 'npm',
+    args: ['exec', '--yes', '--package', fallbackAuraPackage, '--', 'aura', ...commandArgs],
+  };
+}
+
+function isNpmPublishLifecycleInvocation() {
+  return process.env.npm_lifecycle_event === 'publish' && process.env.npm_command === 'publish';
+}
+
+async function runCommand(commandName, invocation, options = {}) {
+  const commandCwd = typeof options.cwd === 'string' && options.cwd ? options.cwd : projectRoot;
+  const commandEnv = options.env && typeof options.env === 'object'
+    ? { ...process.env, ...options.env }
+    : process.env;
+  const log = createCommandLog(commandName);
+  log.stream.write(`[${commandName}] ${new Date().toISOString()} command=${invocation.cmd} ${invocation.args.join(' ')}\n`);
+  let stdoutText = '';
+  let stderrText = '';
+
+  const child = spawn(invocation.cmd, invocation.args, {
+    cwd: commandCwd,
+    stdio: ['inherit', 'pipe', 'pipe'],
+    env: commandEnv,
+  });
+
+  const pipeToConsoleAndLog = (stream, target) => {
+    if (!stream) return;
+    stream.on('data', (chunk) => {
+      const text = typeof chunk === 'string' ? chunk : chunk.toString('utf8');
+      if (target === process.stdout) {
+        stdoutText += text;
+      } else if (target === process.stderr) {
+        stderrText += text;
+      }
+      target.write(chunk);
+      log.stream.write(chunk);
+    });
+  };
+
+  pipeToConsoleAndLog(child.stdout, process.stdout);
+  pipeToConsoleAndLog(child.stderr, process.stderr);
+
+  return new Promise((resolveRun, rejectRun) => {
+    child.on('error', (error) => {
+      log.stream.write(`[${commandName}:error] ${error.message}\n`);
+      log.stream.end(() => {
+        const wrapped = createCliError(error.message, 1);
+        wrapped.stdout = stdoutText;
+        wrapped.stderr = stderrText;
+        wrapped.logPath = log.path;
+        wrapped.commandName = commandName;
+        rejectRun(wrapped);
+      });
+    });
+    child.on('close', (code) => {
+      log.stream.write(`\n[${commandName}:exit] code=${code ?? 1}\n`);
+      log.stream.end(() => {
+        if ((code ?? 1) === 0) {
+          resolveRun();
+        } else {
+          const wrapped = createCliError(`${commandName} failed with exit code ${code ?? 1}.`, code ?? 1);
+          wrapped.stdout = stdoutText;
+          wrapped.stderr = stderrText;
+          wrapped.logPath = log.path;
+          wrapped.commandName = commandName;
+          wrapped.silent = true;
+          rejectRun(wrapped);
+        }
+      });
+    });
+  });
+}
+
+async function chooseDefaultCommand() {
+  printBanner('READY');
+  const choice = await promptSelect(
+    '  Choose command',
+    [
+      { value: 'dev', label: 'Dev' },
+      { value: 'play', label: 'Play' },
+      { value: 'fork', label: 'Fork' },
+      { value: 'session', label: 'Session' },
+      { value: 'publish', label: 'Publish' },
+      { value: 'help', label: 'Help' },
+    ],
+    'dev',
+  );
+  return choice;
+}
+
+async function main() {
+  const parsed = parseArgs(process.argv.slice(2));
+
+  if (parsed.help) {
+    printHelp(parsed.showAll === true);
+    return;
+  }
+
+  let command = parsed.command;
+  let commandArgs = [...parsed.commandArgs];
+
+  if (!command) {
+    if (process.stdin.isTTY && process.stdout.isTTY) {
+      command = await chooseDefaultCommand();
+      if (command === 'help') {
+        printHelp(false);
+        return;
+      }
+      if (command === 'session') {
+        commandArgs = ['start'];
+      }
+    } else {
+      command = 'play';
+    }
+  }
+
+  if (command === 'play') {
+    printBanner('PLAY');
+    printSection(toDisplayTitle(packageName), 'Starting game + dev session...');
+    const externalAssets = await maybePrepareExternalAssets('play');
+    const multiplayerEnv = await resolveLocalMultiplayerCommandEnv();
+    await runCommand(
+      'play',
+      resolveAuraCliInvocation(['run', '--session', '--asset-mode', 'sibling', ...commandArgs]),
+      {
+        cwd: externalAssets.runtimeProjectRoot,
+        env: multiplayerEnv,
+      },
+    );
+    return;
+  }
+
+  if (command === 'fork') {
+    printBanner('FORK');
+    const destinationRoot = await resolveForkDestination(commandArgs);
+    if (!destinationRoot) {
+      printSection(toDisplayTitle(packageName), 'Fork cancelled.');
+      return;
+    }
+    assertForkDestination(destinationRoot);
+    printSection(toDisplayTitle(packageName), `Copying editable package files into ${normalizeDisplayPath(destinationRoot)}...`);
+    copyForkProject(destinationRoot);
+    console.log(`  Fork ready: ${normalizeDisplayPath(destinationRoot)}`);
+    console.log('');
+    console.log('  Next steps:');
+    console.log(`    cd ${normalizeDisplayPath(destinationRoot)}`);
+    console.log('    npm install');
+    console.log('    npm run dev');
+    console.log('');
+    return;
+  }
+
+  if (command === 'dev') {
+    printBanner('DEV');
+    printSection(toDisplayTitle(packageName), 'Starting native dev loop...');
+    const multiplayerEnv = await resolveLocalMultiplayerCommandEnv();
+    await runCommand('dev', resolveAuraCliInvocation(['dev', ...commandArgs]), {
+      env: multiplayerEnv,
+    });
+    return;
+  }
+
+  if (command === 'join') {
+    printBanner('JOIN');
+    let join = null;
+    try {
+      join = parseJoinArgs(commandArgs);
+      const joinLaunchMode = resolveJoinLaunchMode(join.launchMode);
+      assertJoinSupported();
+      const externalAssets = await maybePrepareExternalAssets('join');
+      const multiplayerEnv = await resolveLocalMultiplayerCommandEnv();
+      if (joinLaunchMode === 'play') {
+        printSection(toDisplayTitle(packageName), `Joining room ${join.code}...`);
+        await runCommand(
+          'join',
+          resolveAuraCliInvocation(['run', '--session', '--asset-mode', 'sibling', ...join.passthroughArgs, '--join', join.code]),
+          {
+            cwd: externalAssets.runtimeProjectRoot,
+            env: {
+              ...(multiplayerEnv || {}),
+              AURA_MULTIPLAYER_LAUNCH_ROLE: 'join',
+              AURA_MULTIPLAYER_JOIN_CODE: join.code,
+            },
+          },
+        );
+        return;
+      }
+      printSection(toDisplayTitle(packageName), `Joining room ${join.code} through the native dev loop...`);
+      await runCommand(
+        'join',
+        resolveAuraCliInvocation(['dev', ...join.passthroughArgs, '--join', join.code]),
+        {
+          cwd: externalAssets.runtimeProjectRoot,
+          env: {
+            ...(multiplayerEnv || {}),
+            AURA_MULTIPLAYER_LAUNCH_ROLE: 'join',
+            AURA_MULTIPLAYER_JOIN_CODE: join.code,
+          },
+        },
+      );
+    } catch (error) {
+      throw formatJoinFailure(error, {
+        joinCode: join?.code || null,
+        joinLaunchMode: resolveJoinLaunchMode(join?.launchMode || null),
+      });
+    }
+    return;
+  }
+
+  if (command === 'publish') {
+    printBanner('PUBLISH');
+    if (isNpmPublishLifecycleInvocation()) {
+      printSection(toDisplayTitle(packageName), 'Publish lifecycle detected, skipping wrapper recursion.');
+      return;
+    }
+    printSection(toDisplayTitle(packageName), 'Publishing npm package (source + assets)...');
+    await runCommand('publish', resolveAuraCliInvocation(['publish', ...commandArgs]));
+    return;
+  }
+
+  if (command === 'session') {
+    printBanner('SESSION');
+    printSection(toDisplayTitle(packageName), commandArgs.length > 0 ? 'Delegating to aura session...' : 'Starting session...');
+    const sessionArgs = commandArgs.length > 0 ? commandArgs : ['start'];
+    await runCommand('session', resolveAuraCliInvocation(['session', ...sessionArgs]));
+    return;
+  }
+
+  if (command === 'state') {
+    printBanner('STATE');
+    printSection(toDisplayTitle(packageName), 'Delegating to aura state...');
+    await runCommand('state', resolveAuraCliInvocation(['state', ...commandArgs]));
+    return;
+  }
+
+  if (command === 'inspect') {
+    printBanner('INSPECT');
+    printSection(toDisplayTitle(packageName), 'Delegating to aura inspect...');
+    await runCommand('inspect', resolveAuraCliInvocation(['inspect', ...commandArgs]));
+    return;
+  }
+
+  if (command === 'action') {
+    printBanner('ACTION');
+    printSection(toDisplayTitle(packageName), 'Delegating to aura action...');
+    await runCommand('action', resolveAuraCliInvocation(['action', ...commandArgs]));
+    return;
+  }
+
+  printHelp(false);
+  console.error(`  Unknown command: ${command}`);
+  process.exit(1);
+}
+
+main().catch((error) => {
+  if (!error?.silent) {
+    console.error(error instanceof Error ? error.message : String(error));
+  }
+  process.exit(Number.isInteger(error?.exitCode) ? error.exitCode : 1);
+});