auramaxx 0.1.0 → 0.1.2

package/README.md

@@ -27,15 +27,34 @@ npx auramaxx
 Inside a scaffolded game, use the shorter `auramaxx` alias or the generated
 `npm run ...` scripts for local engine commands.
 
-Play an example:
+## Play an Example
 
 ```bash
-auramaxx play aurasu
+npm install -g auramaxx
+auramaxx play auracraft
 
 # or run a published game wrapper directly
-npx aurasu play
+npx auracraft play
+```
+
+## Fork a Game
+
+```bash
+npm install -g auramaxx
+auramaxx fork auramon
 ```
 
+## Working With AI Agent
+
+Inside your codebase:
+
+```bash
+cd <your-codebase>
+npx -y skills add Aura-Industry/auramaxx
+```
+
+Then use <https://www.aurajs.gg/docs> for engine docs and API references.
+
 ## Multiplayer TL;DR
 
 ```bash
@@ -52,7 +71,7 @@ Keep that same flow and add internet-backed rooms with either:
 - `aura.config.json -> multiplayer.relay = "relay.aurajs.gg"`
 - or `AURA_MULTIPLAYER_RELAY_HOST=relay.aurajs.gg`
 
-Use [`packages/aurascript/docs/external/game-dev-api/multiplayer-quickstart.md`](./packages/aurascript/docs/external/game-dev-api/multiplayer-quickstart.md) for the short multiplayer doc, or [`packages/aurascript/examples/multiplayer-party/README.md`](./packages/aurascript/examples/multiplayer-party/README.md) for the same-project example with diagnostics and room chat.
+Use [Multiplayer Quickstart](https://www.aurajs.gg/docs/multiplayer-quickstart) for the short multiplayer doc, or [Multiplayer Party Example](./packages/aurascript/examples/multiplayer-party/README.md) for the same-project example with diagnostics and room chat.
 
 ## Feature Set
 
@@ -80,13 +99,13 @@ Use [`packages/aurascript/docs/external/game-dev-api/multiplayer-quickstart.md`]
 
 ## Docs
 
-- [`packages/aurascript/README.md`](./packages/aurascript/README.md) - AuraJS overview and public docs entrypoint
-- [`docs/external/game-dev-api/README.md`](./docs/external/game-dev-api/README.md) - game developer handbook
-- [`docs/external/game-dev-api/multiplayer-quickstart.md`](./packages/aurascript/docs/external/game-dev-api/multiplayer-quickstart.md) - shortest multiplayer setup path
-- [`docs/api-contract.md`](./docs/api-contract.md) - frozen core API contract
-- [`docs/api-contract-3d.md`](./docs/api-contract-3d.md) - frozen 3D API contract
-- [`docs/reference/README.md`](./docs/reference/README.md) - exact reference index
-- [`docs/external/api-contract-complete.md`](./docs/external/api-contract-complete.md) - combined public reference
+- [AuraJS README](https://www.aurajs.gg/docs) - AuraJS overview and public docs entrypoint
+- [Game Developer Handbook](https://www.aurajs.gg/docs/handbook) - game developer handbook
+- [Multiplayer Quickstart](https://www.aurajs.gg/docs/multiplayer-quickstart) - shortest multiplayer setup path
+- [Core API Contract](https://www.aurajs.gg/docs/api-contract) - frozen core API contract
+- [3D API Contract](https://www.aurajs.gg/docs/api-contract-3d) - frozen 3D API contract
+- [Exact Reference Index](https://www.aurajs.gg/docs/reference) - exact reference index
+- [Combined Public Reference](https://www.aurajs.gg/docs/reference) - combined public reference
 
 Live docs:
 

package/bin/auramaxx.js

@@ -48,7 +48,7 @@ const COMMANDS = {
   'shell-hook': 'Auto-load .aura env vars on cd (like direnv)',
   play: 'Play an AuraJS game from npm (auramaxx play <game>)',
   fork: 'Fork a published AuraJS game into a local editable project (auramaxx fork <game>)',
-  create: 'Scaffold a new AuraJS game (2d/3d/blank) via AuraJS CLI',
+  create: 'Scaffold a new AuraJS game (2d/3d/multiplayer) via AuraJS CLI',
   make: 'Generate authored AuraJS project files via AuraJS CLI',
   publish: 'Publish current AuraJS game package to npm with guided prompts',
   // diary: 'Append daily diary entries via authenticated CLI path', // Temporarily disabled at root CLI.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "auramaxx",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "AuraJS CLI for creating, playing, and publishing JavaScript-first games.",
   "keywords": [
     "aurajs",
@@ -28,6 +28,7 @@
     "src/server/cli/commands/create.ts",
     "src/server/cli/commands/play.ts",
     "src/server/cli/commands/publish.ts",
+    "src/server/cli/lib/published-game-integrity.ts",
     "src/server/cli/lib/prompt.ts",
     "src/server/cli/lib/theme.ts"
   ],

package/src/server/cli/commands/create.ts

@@ -6,23 +6,21 @@ import { printBanner, printSection, paint, ANSI } from '../lib/theme';
 import { promptInput, promptSelect } from '../lib/prompt';
 
 const TEMPLATE_OPTIONS = [
-  { value: '2d-shooter', label: '[2D] Shooter', aliases: ['1', '2', '2d', 'shooter', '2d shooter'] },
-  { value: '3d-platformer', label: '[3D] Platformer', aliases: ['3', '3d', 'platformer', 'platformers', '3d platformer'] },
-  { value: 'blank', label: 'Blank', aliases: ['b'] },
+  { value: '2d', label: '[2D] Adventure', aliases: ['1', '2', '2d', '2d-adventure', 'adventure-2d'] },
+  { value: '3d', label: '[3D] Adventure', aliases: ['3', '3d', '3d-adventure', 'adventure-3d'] },
+  { value: 'multiplayer', label: '[MP] Multiplayer', aliases: ['4', 'mp', 'multiplayer', 'room', 'room-code', 'local-multiplayer'] },
 ];
-
-const VALID_TEMPLATES = new Set(TEMPLATE_OPTIONS.map((option) => option.value));
 const TEMPLATE_ALIASES: Record<string, string> = {
-  '2d': '2d-shooter',
-  'shooter': '2d-shooter',
-  '2d shooter': '2d-shooter',
-  '2d-shooter': '2d-shooter',
-  '3d': '3d-platformer',
-  'platformer': '3d-platformer',
-  'platformers': '3d-platformer',
-  '3d platformer': '3d-platformer',
-  '3d-platformer': '3d-platformer',
-  'blank': 'blank',
+  '2d': '2d',
+  '2d-adventure': '2d',
+  'adventure-2d': '2d',
+  '3d': '3d',
+  '3d-adventure': '3d',
+  'adventure-3d': '3d',
+  'multiplayer': 'multiplayer',
+  'local-multiplayer': 'multiplayer',
+  'room-code': 'multiplayer',
+  'room': 'multiplayer',
 };
 const COMMAND_DIR = path.dirname(fileURLToPath(import.meta.url));
 const LOCAL_AURAJS_CLI = path.resolve(
@@ -98,15 +96,10 @@ async function resolveGameName(initialName: string | null): Promise<string> {
 
 async function resolveTemplate(initialTemplate: string | null): Promise<string> {
   const normalized = normalizeTemplate(initialTemplate);
-  if (normalized && VALID_TEMPLATES.has(normalized)) {
+  if (normalized) {
     return normalized;
   }
-
-  if (normalized && !VALID_TEMPLATES.has(normalized)) {
-    console.log(`  Unknown template "${normalized}"; choose one below.`);
-  }
-
-  return promptSelect('  Starter template', TEMPLATE_OPTIONS, '2d-shooter');
+  return promptSelect('  Starter template', TEMPLATE_OPTIONS, '2d');
 }
 
 async function main() {
@@ -114,10 +107,13 @@ async function main() {
 
   if (parsed.help) {
     printBanner('CREATE');
-    console.log(`  ${paint('Usage:', ANSI.bold)} auramaxx create [name] [--template <2d-shooter|3d-platformer|blank>] [--skip-install]`);
+    console.log(`  ${paint('Usage:', ANSI.bold)} auramaxx create [name] [--template <2d|3d|multiplayer>] [--skip-install]`);
     console.log('');
     console.log('  Styled wrapper around AuraJS create scaffolding.');
-    console.log(`  ${paint('Example:', ANSI.dim)} auramaxx create my-game --template 3d-platformer`);
+    console.log(`  ${paint('Examples:', ANSI.dim)}`);
+    console.log('    auramaxx create my-game --template 2d');
+    console.log('    auramaxx create my-game --template 3d');
+    console.log('    auramaxx create my-room-game --template multiplayer');
     console.log('');
     return;
   }

package/src/server/cli/commands/play.ts

@@ -3,7 +3,9 @@ import { existsSync, mkdtempSync, readFileSync, rmSync } from 'fs';
 import { homedir, tmpdir } from 'os';
 import { join, resolve } from 'path';
 import { pathToFileURL } from 'url';
-import { printBanner, printSection, paint, ANSI } from '../lib/theme';
+import { printBanner, printSection, paint, ANSI, createProgressDisplay, printComplete } from '../lib/theme';
+import { promptSelect } from '../lib/prompt';
+import { PublishedGameIntegrityError } from '../lib/published-game-integrity';
 import {
   assertPublishedGameBinIntegrity,
   buildPublishedGameLaunchEnv,
@@ -108,6 +110,10 @@ function resolveNpmCommand(): string {
   return process.platform === 'win32' ? 'npm.cmd' : 'npm';
 }
 
+function resolveAuramaxxCommand(): string {
+  return process.platform === 'win32' ? 'auramaxx.cmd' : 'auramaxx';
+}
+
 function normalizeRelativePath(pathLike: string): string {
   return String(pathLike || '')
     .trim()
@@ -180,22 +186,69 @@ function formatInstallError(error: unknown, packageSpec: string): Error {
   return new Error(`Refusing to run ${packageSpec}: ${message}`);
 }
 
+function isUnsupportedAurajsWrapperError(error: unknown): error is PublishedGameIntegrityError {
+  return error instanceof PublishedGameIntegrityError
+    && error.reasonCode === 'published_game_aurajs_version_unsupported';
+}
+
+async function promptUpgradeAuramaxx(expectedAurajsVersion: string): Promise<boolean> {
+  console.log('');
+  console.log(`  ${paint('AuraMaxx update required', ANSI.bold)}`);
+  console.log(`  ${paint(`This game uses @auraindustry/aurajs ${expectedAurajsVersion}.`, ANSI.dim)}`);
+  console.log(`  ${paint('Your installed AuraMaxx does not recognize that play wrapper yet.', ANSI.dim)}`);
+  console.log('');
+
+  const choice = await promptSelect(
+    '  Update AuraMaxx now?',
+    [
+      { value: 'update', label: 'Yes, update and retry', aliases: ['y', 'yes', '1'] },
+      { value: 'cancel', label: 'No, cancel', aliases: ['n', 'no', '2'] },
+    ],
+    'update',
+  );
+
+  return choice === 'update';
+}
+
+function installLatestAuramaxx(): void {
+  console.log('');
+  console.log(`  ${paint('Installing latest AuraMaxx...', ANSI.bold)}`);
+  console.log('');
+  execFileSync(resolveNpmCommand(), ['install', '-g', 'auramaxx@latest', '--foreground-scripts'], {
+    stdio: 'inherit',
+    timeout: 120000,
+  });
+}
+
+function relaunchWithUpdatedAuramaxx(argv: string[]): never {
+  printComplete('AuraMaxx updated. Relaunching play...');
+  execFileSync(resolveAuramaxxCommand(), ['play', ...argv], {
+    stdio: 'inherit',
+    env: process.env,
+  });
+  process.exit(0);
+}
+
 export async function installVerifiedGamePackage(
   plan: PlayCommandPlan,
   {
     execFileSyncImpl = execFileSync,
     env = process.env,
+    onProgress,
   }: {
     execFileSyncImpl?: typeof execFileSync;
     env?: NodeJS.ProcessEnv;
+    onProgress?: (step: number, label: string, detail?: string) => void;
   } = {},
 ) {
   if (!plan.name || !plan.packageName) {
     throw new Error('installVerifiedGamePackage requires a resolved package spec.');
   }
 
+  onProgress?.(1, 'Resolving package', plan.packageName);
   const installRoot = mkdtempSync(join(tmpdir(), 'auramaxx-play-'));
   try {
+    onProgress?.(2, 'Installing verified wrapper', plan.name);
     execFileSyncImpl(resolveNpmCommand(), buildSecureInstallArgs(plan.name, installRoot), {
       stdio: ['ignore', 'pipe', 'pipe'],
       env: {
@@ -212,6 +265,7 @@ export async function installVerifiedGamePackage(
 
     const gamePackage = readInstalledPackageJson(packageRoot);
     const dependencySpec = String(gamePackage?.dependencies?.['@auraindustry/aurajs'] || '').trim();
+    onProgress?.(3, 'Verifying package integrity', dependencySpec || plan.packageName);
     const integrity = assertPublishedGameBinIntegrity({
       packageRoot,
       projectPackage: gamePackage,
@@ -245,6 +299,9 @@ export async function installVerifiedGamePackage(
     };
   } catch (error: unknown) {
     rmSync(installRoot, { recursive: true, force: true });
+    if (error instanceof PublishedGameIntegrityError) {
+      throw error;
+    }
     throw formatInstallError(error, plan.name);
   }
 }
@@ -296,14 +353,20 @@ export async function main(argv: string[] = process.argv.slice(2)) {
 
   printBanner(plan.name.toUpperCase());
   printSection(plan.name, describeForwardedCommand(plan.forwardedArgs[0] || 'play'));
+  const progress = createProgressDisplay(4);
 
   let install: Awaited<ReturnType<typeof installVerifiedGamePackage>> | null = null;
   try {
-    install = await installVerifiedGamePackage(plan);
+    install = await installVerifiedGamePackage(plan, {
+      onProgress(step, label, detail) {
+        progress.update(step, label, detail);
+      },
+    });
     const env = buildPublishedGameLaunchEnv(
       process.env,
       plan.forwardedArgs[0] === 'join' ? { AURA_GAME_JOIN_MODE: 'play' } : {},
     );
+    progress.update(4, 'Launching game', plan.forwardedArgs[0] || 'play');
     execFileSync(process.execPath, [install.binAbsolutePath, ...plan.forwardedArgs], {
       stdio: 'inherit',
       cwd: install.packageRoot,
@@ -316,7 +379,36 @@ export async function main(argv: string[] = process.argv.slice(2)) {
   }
 }
 if (import.meta.url === pathToFileURL(process.argv[1]).href) {
-  main().catch((err) => {
+  const cliArgv = process.argv.slice(2);
+  main(cliArgv).catch((err) => {
+    if (isUnsupportedAurajsWrapperError(err)) {
+      const expectedAurajsVersion = String(err.details.expectedAurajsVersion || '').trim() || '<unknown>';
+      (async () => {
+        const shouldUpdate = await promptUpgradeAuramaxx(expectedAurajsVersion);
+        if (!shouldUpdate) {
+          console.error(err.message);
+          process.exit(1);
+        }
+
+        try {
+          installLatestAuramaxx();
+          relaunchWithUpdatedAuramaxx(cliArgv);
+        } catch (updateError) {
+          console.error('');
+          console.error(
+            updateError instanceof Error
+              ? updateError.message
+              : String(updateError),
+          );
+          console.error('  Manual fallback: npm install -g auramaxx@latest');
+          process.exit(1);
+        }
+      })().catch((promptError) => {
+        console.error(promptError instanceof Error ? promptError.message : String(promptError));
+        process.exit(1);
+      });
+      return;
+    }
     console.error(err instanceof Error ? err.message : String(err));
     const status = (err as { status?: number; exitCode?: number })?.status
       ?? (err as { status?: number; exitCode?: number })?.exitCode

package/src/server/cli/lib/published-game-integrity.ts

@@ -0,0 +1,572 @@
+import { createHash, createPublicKey, verify } from 'crypto';
+import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'fs';
+import { dirname, join, relative, resolve } from 'path';
+
+const PACKAGE_INTEGRITY_SCHEMA = 'aurajs.package-integrity.v1';
+const PACKAGE_INTEGRITY_MANIFEST_PATH = 'aura.package-integrity.json';
+const PACKAGE_INTEGRITY_SIGNATURE_PATH = 'aura.package-integrity.sig';
+const PACKAGE_SIGNER_TRUST_STORE_PATH = 'published-game-signers.json';
+const EXACT_SEMVER_PATTERN = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+const PLAY_WRAPPER_REQUIRED_MARKERS = [
+  '#!/usr/bin/env node',
+  'const fallbackAuraPackage =',
+  "const MINIMAL_COMMANDS = ['dev', 'join', 'play', 'fork', 'publish', 'session'];",
+  "const ALL_COMMANDS = ['dev', 'join', 'play', 'fork', 'publish', 'session', 'state', 'inspect', 'action'];",
+  "args: ['exec', '--yes', '--package', fallbackAuraPackage, '--', 'aura', ...commandArgs]",
+] as const;
+
+export class PublishedGameIntegrityError extends Error {
+  reasonCode: string;
+  details: Record<string, unknown>;
+
+  constructor(reasonCode: string, message: string, details: Record<string, unknown> = {}) {
+    super(message);
+    this.name = 'PublishedGameIntegrityError';
+    this.reasonCode = reasonCode;
+    this.details = details;
+  }
+}
+
+function normalizeRelativePath(pathLike: string): string {
+  return String(pathLike || '')
+    .trim()
+    .replace(/^[.][\\/]/, '')
+    .replaceAll('\\', '/');
+}
+
+function normalizeText(value: string): string {
+  return String(value || '').replace(/\r\n?/g, '\n');
+}
+
+function normalizeString(value: unknown): string | null {
+  return typeof value === 'string' && value.trim().length > 0
+    ? value.trim()
+    : null;
+}
+
+function sha256Buffer(buffer: Buffer): string {
+  return createHash('sha256').update(buffer).digest('hex');
+}
+
+function sha256Text(value: string): string {
+  return sha256Buffer(Buffer.from(normalizeText(value), 'utf8'));
+}
+
+function readJsonFile(path: string): Record<string, unknown> {
+  try {
+    return JSON.parse(readFileSync(path, 'utf8')) as Record<string, unknown>;
+  } catch (error) {
+    throw new PublishedGameIntegrityError(
+      'published_game_json_invalid',
+      `Failed to parse JSON at ${path}: ${error instanceof Error ? error.message : String(error)}`,
+      { path },
+    );
+  }
+}
+
+function listRelativeFiles(root: string, current = root, acc: string[] = []): string[] {
+  for (const entry of readdirSync(current, { withFileTypes: true })) {
+    const fullPath = join(current, entry.name);
+    if (entry.isDirectory()) {
+      listRelativeFiles(root, fullPath, acc);
+      continue;
+    }
+    if (entry.isFile()) {
+      acc.push(normalizeRelativePath(relative(root, fullPath)));
+    }
+  }
+  return acc;
+}
+
+function listHashedPackageFiles(root: string, current = root, acc: Array<{ path: string; size: number; sha256: string }> = []) {
+  for (const entry of readdirSync(current, { withFileTypes: true })) {
+    const fullPath = join(current, entry.name);
+    const relativePath = normalizeRelativePath(relative(root, fullPath));
+
+    if (relativePath === PACKAGE_INTEGRITY_MANIFEST_PATH || relativePath === PACKAGE_INTEGRITY_SIGNATURE_PATH) {
+      continue;
+    }
+    if (entry.isSymbolicLink()) {
+      throw new PublishedGameIntegrityError(
+        'published_game_symlink_not_allowed',
+        `Published game package may not contain symlinks: ${relativePath}`,
+        { path: relativePath },
+      );
+    }
+    if (entry.isDirectory()) {
+      listHashedPackageFiles(root, fullPath, acc);
+      continue;
+    }
+    if (!entry.isFile()) {
+      continue;
+    }
+
+    const bytes = readFileSync(fullPath);
+    acc.push({
+      path: relativePath,
+      size: bytes.length,
+      sha256: sha256Buffer(bytes),
+    });
+  }
+
+  acc.sort((left, right) => left.path.localeCompare(right.path));
+  return acc;
+}
+
+function sortKeysDeep(value: unknown): unknown {
+  if (Array.isArray(value)) {
+    return value.map((entry) => sortKeysDeep(entry));
+  }
+  if (!value || typeof value !== 'object') {
+    return value;
+  }
+
+  const sorted: Record<string, unknown> = {};
+  for (const key of Object.keys(value as Record<string, unknown>).sort()) {
+    sorted[key] = sortKeysDeep((value as Record<string, unknown>)[key]);
+  }
+  return sorted;
+}
+
+function stableSerialize(value: unknown): string {
+  return JSON.stringify(sortKeysDeep(value));
+}
+
+function normalizeBinMap(projectPackage: Record<string, unknown>): Record<string, string> {
+  if (typeof projectPackage?.bin === 'string' && projectPackage.bin.trim().length > 0) {
+    return {
+      [String(projectPackage?.name || 'game').split('/').pop() || 'game']: normalizeRelativePath(projectPackage.bin),
+    };
+  }
+
+  const normalized: Record<string, string> = {};
+  for (const key of Object.keys((projectPackage?.bin || {}) as Record<string, unknown>).sort()) {
+    const value = (projectPackage.bin as Record<string, unknown>)[key];
+    if (typeof value !== 'string' || value.trim().length === 0) {
+      continue;
+    }
+    normalized[key] = normalizeRelativePath(value);
+  }
+  return normalized;
+}
+
+function resolveProjectBinEntries(projectPackage: Record<string, unknown>, packageName: string | null) {
+  const normalizedPackageName = normalizeString(packageName) || normalizeString(projectPackage?.name) || 'game';
+  if (typeof projectPackage?.bin === 'string' && projectPackage.bin.trim().length > 0) {
+    return [{
+      name: normalizedPackageName.split('/').pop() || normalizedPackageName,
+      relativePath: normalizeRelativePath(projectPackage.bin),
+    }];
+  }
+
+  return Object.entries((projectPackage?.bin || {}) as Record<string, unknown>)
+    .filter(([, value]) => typeof value === 'string' && value.trim().length > 0)
+    .map(([name, value]) => ({
+      name,
+      relativePath: normalizeRelativePath(String(value)),
+    }));
+}
+
+function assertPlayWrapperContract(relativePath: string, wrapperText: string): { markers: string[] } {
+  const normalized = normalizeText(wrapperText);
+  const missingMarkers = PLAY_WRAPPER_REQUIRED_MARKERS.filter((marker) => !normalized.includes(marker));
+  if (missingMarkers.length > 0) {
+    throw new PublishedGameIntegrityError(
+      'published_game_bin_wrapper_contract_invalid',
+      `Bin target "${relativePath}" does not satisfy the AuraJS play wrapper contract.`,
+      {
+        relativePath,
+        missingMarkers,
+      },
+    );
+  }
+
+  return {
+    markers: [...PLAY_WRAPPER_REQUIRED_MARKERS],
+  };
+}
+
+function normalizeAuthoredMetadata(packageRoot: string) {
+  const configPath = resolve(packageRoot, 'aura.config.json');
+  if (!existsSync(configPath)) {
+    return {
+      identity: null,
+      window: null,
+    };
+  }
+
+  const config = readJsonFile(configPath);
+  const iconPath = normalizeString((config.identity as Record<string, unknown> | undefined)?.icon);
+  const normalizedIconPath = iconPath ? normalizeRelativePath(iconPath) : null;
+  const iconAbsolutePath = normalizedIconPath ? resolve(packageRoot, normalizedIconPath) : null;
+  const iconBytes = iconAbsolutePath && existsSync(iconAbsolutePath) && lstatSync(iconAbsolutePath).isFile()
+    ? readFileSync(iconAbsolutePath)
+    : null;
+
+  return {
+    identity: {
+      name: normalizeString((config.identity as Record<string, unknown> | undefined)?.name),
+      version: normalizeString((config.identity as Record<string, unknown> | undefined)?.version),
+      executable: normalizeString((config.identity as Record<string, unknown> | undefined)?.executable),
+      icon: normalizedIconPath,
+      iconAsset: {
+        path: normalizedIconPath,
+        exists: Boolean(iconBytes),
+        size: iconBytes ? iconBytes.length : null,
+        sha256: iconBytes ? sha256Buffer(iconBytes) : null,
+      },
+    },
+    window: {
+      title: normalizeString((config.window as Record<string, unknown> | undefined)?.title),
+    },
+  };
+}
+
+function updateSignerTrustStore(trustRoot: string | null, packageName: string, packageVersion: string | null, signerFingerprint: string) {
+  if (!trustRoot) {
+    return {
+      status: 'unchecked',
+      storePath: null,
+    };
+  }
+
+  const storePath = resolve(trustRoot, PACKAGE_SIGNER_TRUST_STORE_PATH);
+  const existingEntries = existsSync(storePath) ? readJsonFile(storePath) : {};
+  const existing = (existingEntries[packageName] as Record<string, unknown> | undefined) || null;
+  const existingFingerprint = normalizeString(existing?.signerFingerprint);
+  if (existingFingerprint && existingFingerprint !== signerFingerprint) {
+    throw new PublishedGameIntegrityError(
+      'published_game_signer_changed',
+      `Published game signer changed for ${packageName}: expected ${existingFingerprint}, got ${signerFingerprint}.`,
+      {
+        packageName,
+        packageVersion,
+        expectedFingerprint: existingFingerprint,
+        actualFingerprint: signerFingerprint,
+        storePath,
+      },
+    );
+  }
+
+  const now = new Date().toISOString();
+  const nextEntries = {
+    ...existingEntries,
+    [packageName]: {
+      signerFingerprint,
+      firstSeenAt: existing?.firstSeenAt || now,
+      lastSeenAt: now,
+      lastVersion: packageVersion,
+    },
+  };
+
+  mkdirSync(dirname(storePath), { recursive: true });
+  writeFileSync(storePath, `${JSON.stringify(nextEntries, null, 2)}\n`, 'utf8');
+
+  return {
+    status: existing ? 'trusted' : 'trusted_first_use',
+    storePath,
+  };
+}
+
+export function buildPublishedGameLaunchEnv(
+  source: NodeJS.ProcessEnv,
+  explicit: Record<string, string> = {},
+): NodeJS.ProcessEnv {
+  return {
+    ...(source || {}),
+    ...explicit,
+  };
+}
+
+export function assertPublishedGameBinIntegrity(input: {
+  packageRoot: string;
+  projectPackage?: Record<string, unknown> | null;
+  packageName?: string | null;
+  expectedAurajsVersion?: string | null;
+}) {
+  const packageRoot = resolve(input.packageRoot);
+  const packageJsonPath = resolve(packageRoot, 'package.json');
+  if (!existsSync(packageJsonPath)) {
+    throw new PublishedGameIntegrityError(
+      'published_game_package_json_missing',
+      `Could not read installed package metadata at ${packageJsonPath}.`,
+      { packageJsonPath },
+    );
+  }
+
+  const projectPackage = input.projectPackage || readJsonFile(packageJsonPath);
+  const packageName = normalizeString(input.packageName) || normalizeString(projectPackage?.name);
+  const dependencySpec = normalizeString((projectPackage.dependencies as Record<string, unknown> | undefined)?.['@auraindustry/aurajs']);
+  if (!dependencySpec) {
+    throw new PublishedGameIntegrityError(
+      'published_game_aurajs_dependency_missing',
+      'Published AuraJS games must depend on @auraindustry/aurajs.',
+      { packageJsonPath },
+    );
+  }
+  if (!EXACT_SEMVER_PATTERN.test(dependencySpec)) {
+    throw new PublishedGameIntegrityError(
+      'published_game_aurajs_dependency_unpinned',
+      'Published AuraJS games must pin @auraindustry/aurajs to an exact version.',
+      { dependencySpec, packageJsonPath },
+    );
+  }
+  if (normalizeString(input.expectedAurajsVersion) && dependencySpec !== input.expectedAurajsVersion) {
+    throw new PublishedGameIntegrityError(
+      'published_game_aurajs_dependency_version_mismatch',
+      `Expected @auraindustry/aurajs version ${input.expectedAurajsVersion}, found ${dependencySpec}.`,
+      {
+        dependencySpec,
+        expectedAurajsVersion: input.expectedAurajsVersion,
+        packageJsonPath,
+      },
+    );
+  }
+
+  const binEntries = resolveProjectBinEntries(projectPackage, packageName);
+  if (binEntries.length === 0) {
+    throw new PublishedGameIntegrityError(
+      'published_game_bin_missing',
+      'Published AuraJS games must declare a generated wrapper entrypoint in package.json -> bin.',
+      { packageJsonPath },
+    );
+  }
+
+  for (const entry of binEntries) {
+    if (!entry.relativePath.startsWith('bin/')) {
+      throw new PublishedGameIntegrityError(
+        'published_game_bin_path_outside_bin_dir',
+        `Bin target "${entry.relativePath}" must live under bin/.`,
+        { entry },
+      );
+    }
+  }
+
+  const binDir = resolve(packageRoot, 'bin');
+  if (!existsSync(binDir)) {
+    throw new PublishedGameIntegrityError(
+      'published_game_bin_dir_missing',
+      'Published AuraJS games must include a bin/ directory.',
+      { binDir },
+    );
+  }
+
+  const actualBinFiles = listRelativeFiles(binDir).map((entry) => normalizeRelativePath(join('bin', entry)));
+  const declaredBinPaths = [...new Set(binEntries.map((entry) => entry.relativePath))];
+  const declaredBinSet = new Set(declaredBinPaths);
+  const unexpectedFiles = actualBinFiles.filter((entry) => !declaredBinSet.has(entry));
+  if (unexpectedFiles.length > 0) {
+    throw new PublishedGameIntegrityError(
+      'published_game_bin_unexpected_file',
+      `Published AuraJS games may not ship extra bin/ files: ${unexpectedFiles.join(', ')}`,
+      {
+        declaredBinPaths,
+        unexpectedFiles,
+      },
+    );
+  }
+
+  const verifiedFiles = [];
+  for (const relativePath of declaredBinPaths) {
+    const absolutePath = resolve(packageRoot, relativePath);
+    if (!existsSync(absolutePath)) {
+      throw new PublishedGameIntegrityError(
+        'published_game_bin_target_missing',
+        `Published game bin target "${relativePath}" is missing from the installed package.`,
+        { relativePath, absolutePath },
+      );
+    }
+
+    const wrapperText = readFileSync(absolutePath, 'utf8');
+    const contract = assertPlayWrapperContract(relativePath, wrapperText);
+
+    verifiedFiles.push({
+      relativePath,
+      absolutePath,
+      hash: sha256Text(wrapperText),
+      contractMarkers: contract.markers,
+    });
+  }
+
+  return {
+    reasonCode: 'published_game_bin_integrity_ok',
+    packageName,
+    aurajsDependency: {
+      spec: dependencySpec,
+      wrapperContract: 'aurajs.play-wrapper.v1',
+    },
+    bin: {
+      entries: binEntries,
+      declaredFiles: declaredBinPaths,
+      actualFiles: actualBinFiles,
+      verifiedFiles,
+    },
+  };
+}
+
+export function verifyPublishedGamePackageIntegrity(input: {
+  packageRoot: string;
+  expectedPackageName?: string | null;
+  trustRoot?: string | null;
+}) {
+  const packageRoot = resolve(input.packageRoot);
+  const manifestPath = resolve(packageRoot, PACKAGE_INTEGRITY_MANIFEST_PATH);
+  const signaturePath = resolve(packageRoot, PACKAGE_INTEGRITY_SIGNATURE_PATH);
+  if (!existsSync(manifestPath) || !existsSync(signaturePath)) {
+    throw new PublishedGameIntegrityError(
+      'published_game_integrity_artifacts_missing',
+      `Published game package must include ${PACKAGE_INTEGRITY_MANIFEST_PATH} and ${PACKAGE_INTEGRITY_SIGNATURE_PATH}.`,
+      { manifestPath, signaturePath },
+    );
+  }
+
+  const manifest = readJsonFile(manifestPath);
+  const signature = String(readFileSync(signaturePath, 'utf8') || '').trim();
+  if (normalizeString(manifest?.schema) !== PACKAGE_INTEGRITY_SCHEMA) {
+    throw new PublishedGameIntegrityError(
+      'published_game_integrity_schema_invalid',
+      `Expected ${PACKAGE_INTEGRITY_SCHEMA}, found ${manifest?.schema || '<missing>'}.`,
+      { schema: manifest?.schema || null },
+    );
+  }
+  if (!signature) {
+    throw new PublishedGameIntegrityError(
+      'published_game_integrity_signature_missing',
+      `${PACKAGE_INTEGRITY_SIGNATURE_PATH} is empty.`,
+      { signaturePath },
+    );
+  }
+
+  const publicKeyPem = normalizeString((manifest.signer as Record<string, unknown> | undefined)?.publicKeyPem);
+  const signerFingerprint = normalizeString((manifest.signer as Record<string, unknown> | undefined)?.fingerprint);
+  if (!publicKeyPem || !signerFingerprint) {
+    throw new PublishedGameIntegrityError(
+      'published_game_signer_missing',
+      'Package integrity manifest is missing signer metadata.',
+      {},
+    );
+  }
+
+  const actualFingerprint = sha256Buffer(
+    createPublicKey(publicKeyPem).export({ format: 'der', type: 'spki' }) as Buffer,
+  );
+  if (actualFingerprint !== signerFingerprint) {
+    throw new PublishedGameIntegrityError(
+      'published_game_signer_fingerprint_mismatch',
+      'Package integrity signer fingerprint does not match the embedded public key.',
+      {
+        expectedFingerprint: signerFingerprint,
+        actualFingerprint,
+      },
+    );
+  }
+
+  const signatureOk = verify(
+    null,
+    Buffer.from(stableSerialize(manifest)),
+    publicKeyPem,
+    Buffer.from(signature, 'base64'),
+  );
+  if (!signatureOk) {
+    throw new PublishedGameIntegrityError(
+      'published_game_integrity_signature_invalid',
+      'Package integrity signature verification failed.',
+      { signerFingerprint },
+    );
+  }
+
+  if (normalizeString(input.expectedPackageName) && normalizeString((manifest.package as Record<string, unknown> | undefined)?.name) !== input.expectedPackageName) {
+    throw new PublishedGameIntegrityError(
+      'published_game_package_name_mismatch',
+      `Expected published package ${input.expectedPackageName}, found ${(manifest.package as Record<string, unknown> | undefined)?.name || '<missing>'}.`,
+      {
+        expectedPackageName: input.expectedPackageName,
+        actualPackageName: (manifest.package as Record<string, unknown> | undefined)?.name || null,
+      },
+    );
+  }
+
+  const actualFiles = listHashedPackageFiles(packageRoot);
+  const expectedFiles = Array.isArray(manifest.files) ? manifest.files as Array<Record<string, unknown>> : [];
+  const expectedByPath = new Map(expectedFiles.map((entry) => [normalizeRelativePath(String(entry.path || '')), entry]));
+  const actualByPath = new Map(actualFiles.map((entry) => [entry.path, entry]));
+  const missing = [];
+  const mismatched = [];
+  for (const [path, expected] of expectedByPath) {
+    const actual = actualByPath.get(path);
+    if (!actual) {
+      missing.push(path);
+      continue;
+    }
+    if (actual.sha256 !== expected.sha256 || actual.size !== expected.size) {
+      mismatched.push({
+        path,
+        expected,
+        actual,
+      });
+    }
+  }
+  const extra = actualFiles.filter((entry) => !expectedByPath.has(entry.path)).map((entry) => entry.path);
+  if (missing.length > 0 || mismatched.length > 0 || extra.length > 0) {
+    throw new PublishedGameIntegrityError(
+      'published_game_file_mismatch',
+      'Published game package contents do not match the signed integrity manifest.',
+      {
+        missing,
+        extra,
+        mismatched,
+      },
+    );
+  }
+
+  const packageJson = readJsonFile(resolve(packageRoot, 'package.json'));
+  const actualPackageMetadata = {
+    name: normalizeString(packageJson?.name),
+    version: normalizeString(packageJson?.version),
+    description: normalizeString(packageJson?.description),
+    type: normalizeString(packageJson?.type),
+    aurajsVersion: normalizeString((packageJson.dependencies as Record<string, unknown> | undefined)?.['@auraindustry/aurajs']),
+    bin: normalizeBinMap(packageJson),
+  };
+  if (stableSerialize(actualPackageMetadata) !== stableSerialize(manifest.package || {})) {
+    throw new PublishedGameIntegrityError(
+      'published_game_package_metadata_mismatch',
+      'Installed package.json metadata does not match the signed integrity manifest.',
+      {
+        expected: manifest.package || null,
+        actual: actualPackageMetadata,
+      },
+    );
+  }
+
+  const actualAuthoredMetadata = normalizeAuthoredMetadata(packageRoot);
+  if (stableSerialize(actualAuthoredMetadata) !== stableSerialize((manifest.publishedMetadata as Record<string, unknown> | undefined)?.authored || {})) {
+    throw new PublishedGameIntegrityError(
+      'published_game_authored_metadata_mismatch',
+      'Installed authored game metadata does not match the signed integrity manifest.',
+      {
+        expected: (manifest.publishedMetadata as Record<string, unknown> | undefined)?.authored || null,
+        actual: actualAuthoredMetadata,
+      },
+    );
+  }
+
+  const trust = updateSignerTrustStore(
+    normalizeString(input.trustRoot),
+    normalizeString(actualPackageMetadata.name) || '<unknown>',
+    normalizeString(actualPackageMetadata.version),
+    signerFingerprint,
+  );
+
+  return {
+    reasonCode: 'published_game_package_integrity_ok',
+    manifestPath,
+    signaturePath,
+    packageName: actualPackageMetadata.name,
+    packageVersion: actualPackageMetadata.version,
+    signerFingerprint,
+    trust,
+    fileCount: expectedFiles.length,
+    publishedMetadata: manifest.publishedMetadata || null,
+  };
+}

package/src/server/cli/lib/theme.ts

@@ -221,6 +221,64 @@ export function printComplete(message: string): void {
   console.log('');
 }
 
+function stripAnsi(text: string): string {
+  return text.replace(/\x1b\[[0-9;]*m/g, '');
+}
+
+function formatProgressBar(current: number, total: number, width: number): string {
+  const safeTotal = Math.max(1, total);
+  const clamped = Math.max(0, Math.min(current, safeTotal));
+  const filled = Math.round((clamped / safeTotal) * width);
+  const active = paint('/'.repeat(filled), ANSI.fgAccent, ANSI.bold);
+  const pending = paint('-'.repeat(Math.max(0, width - filled)), ANSI.dim);
+  return `[${active}${pending}]`;
+}
+
+export interface ProgressDisplay {
+  update(step: number, label: string, detail?: string): void;
+  complete(label?: string, detail?: string): void;
+}
+
+export function createProgressDisplay(totalSteps: number, width = 24): ProgressDisplay {
+  const stdout = process.stdout;
+  const interactive = stdout.isTTY;
+  let renderedLineCount = 0;
+
+  function draw(step: number, label: string, detail?: string) {
+    const safeStep = Math.max(0, Math.min(step, totalSteps));
+    const titleLine = `  ${paint('//', ANSI.fgAccent, ANSI.bold)} ${paint(label, ANSI.bold)} ${paint(`${safeStep}/${totalSteps}`, ANSI.dim)} ${formatProgressBar(safeStep, totalSteps, width)}`;
+    const lines = detail ? [titleLine, `     ${paint(detail, ANSI.dim)}`] : [titleLine];
+
+    if (interactive && renderedLineCount > 0) {
+      stdout.write(`\u001b[${renderedLineCount}A`);
+      for (let index = 0; index < renderedLineCount; index += 1) {
+        stdout.write('\u001b[2K');
+        stdout.write('\u001b[1B');
+      }
+      stdout.write(`\u001b[${renderedLineCount}A`);
+    }
+
+    for (const line of lines) {
+      if (interactive) {
+        stdout.write('\u001b[2K');
+        stdout.write(`${line}\n`);
+      } else {
+        console.log(stripAnsi(line));
+      }
+    }
+    renderedLineCount = lines.length;
+  }
+
+  return {
+    update(step: number, label: string, detail?: string) {
+      draw(step, label, detail);
+    },
+    complete(label = 'Ready', detail?: string) {
+      draw(totalSteps, label, detail);
+    },
+  };
+}
+
 // ── Seed phrase box (security-critical) ──────────────────────
 
 /**