auramaxx 0.1.2 → 0.1.4

package/README.md

@@ -1,5 +1,7 @@
 # AuraJS
 
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
 Write JavaScript 2D and 3D games, compile to native.
 Create, play, and publish from your terminal.
 
@@ -37,6 +39,8 @@ auramaxx play auracraft
 npx auracraft play
 ```
 
+![Auracraft demo](https://aurajs.gg/auracraft-demo.gif)
+
 ## Fork a Game
 
 ```bash

package/bin/auramaxx.js

@@ -49,8 +49,21 @@ const COMMANDS = {
   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/multiplayer) via AuraJS CLI',
+  dev: 'Run the AuraJS local dev loop in the current project',
+  build: 'Build the current AuraJS project',
   make: 'Generate authored AuraJS project files via AuraJS CLI',
+  explain: 'Explain the current AuraJS project surface',
+  check: 'Validate the current AuraJS project surface',
   publish: 'Publish current AuraJS game package to npm with guided prompts',
+  'external-assets': 'Stage self-hosted external asset manifests for the current AuraJS project',
+  run: 'Run the current AuraJS project with lower-level launch/session control',
+  clean: 'Clean generated AuraJS project output',
+  test: 'Run AuraJS project tests',
+  conformance: 'Run AuraJS project conformance checks',
+  state: 'Run AuraJS project state tools',
+  inspect: 'Run AuraJS project inspect tools',
+  action: 'Run AuraJS project action tools',
+  session: 'Run AuraJS project session tools',
   // diary: 'Append daily diary entries via authenticated CLI path', // Temporarily disabled at root CLI.
   // apikey: 'List/validate/set/delete API keys', // Temporarily disabled at root CLI.
   // quickhack: 'Generate random tutorial secret, run set+inject, and print copyable commands', // Temporarily disabled at root CLI.
@@ -122,7 +135,26 @@ const SHORTCUT_COMMANDS = [];
 // ];
 
 const DEFAULT_ADMIN = ['start', 'status', 'init', 'mcp', 'skill', 'auth'];
-const AURAJS_COMMANDS = ['create', 'make', 'play', 'fork', 'publish'];
+const AURAJS_COMMANDS = [
+  'create',
+  'dev',
+  'build',
+  'play',
+  'make',
+  'explain',
+  'check',
+  'publish',
+  'external-assets',
+  'run',
+  'clean',
+  'test',
+  'conformance',
+  'state',
+  'inspect',
+  'action',
+  'session',
+  'fork',
+];
 const HIDDEN_HELP_COMMANDS = new Set(['wallet']);
 
 const COMMON_EXAMPLES = [
@@ -131,6 +163,8 @@ const COMMON_EXAMPLES = [
   { cmd: 'aura skill --doctor', note: 'Check skill installation status' },
   { cmd: 'aura mcp --install', note: 'Install MCP config for supported clients' },
   { cmd: 'auramaxx make scene Scene1', note: 'Generate a scene in the current AuraJS project' },
+  { cmd: 'auramaxx check', note: 'Validate the current AuraJS project from any project subdirectory' },
+  { cmd: 'auramaxx external-assets generate --public-base-url https://cdn.example.com/my-game', note: 'Stage self-hosted asset manifests for the current AuraJS project' },
   { cmd: 'auramaxx fork aurasu ./aurasu-local', note: 'Fork a published AuraJS game into a local editable project' },
   // { cmd: 'aura diary write --entry "heartbeat ok"', note: 'Append a daily diary entry (auth-aware)' }, // Temporarily disabled at root CLI.
   // { cmd: 'aura get OURSECRET', note: 'Read a credential' }, // Temporarily disabled at root CLI.
@@ -673,10 +707,18 @@ function getUpdateCachePath() {
   return path.join(dataDir, `update-check-${key}.json`);
 }
 
+function resolveNpmCommand() {
+  return process.platform === 'win32' ? 'npm.cmd' : 'npm';
+}
+
+function resolveAuramaxxCommand() {
+  return process.platform === 'win32' ? 'auramaxx.cmd' : 'auramaxx';
+}
+
 function getGlobalInstalledAuramaxxVersion() {
   const timeoutMs = Number(process.env.AURA_UPDATE_CHECK_TIMEOUT_MS || '1200');
   try {
-    const out = execFileSync('npm', ['list', '-g', 'auramaxx', '--json'], {
+    const out = execFileSync(resolveNpmCommand(), ['list', '-g', 'auramaxx', '--json'], {
       cwd: root,
       stdio: ['ignore', 'pipe', 'ignore'],
       timeout: timeoutMs,
@@ -705,7 +747,7 @@ function formatUpdateAvailableLine(current, latest) {
   return `⚠️  Update available: aura${normalizedCurrent} → aura${normalizedLatest}`;
 }
 
-function maybePrintUpdateNotice() {
+function resolveUpdateNoticeState() {
   if (process.env.AURA_NO_UPDATE_CHECK === '1' || process.env.CI === 'true') return;
 
   const now = Date.now();
@@ -736,10 +778,9 @@ function maybePrintUpdateNotice() {
     }
 
     if (cachedLatest && compareVersions(cachedLatest, effectiveCurrent || '') > 0) {
-      console.log(`\n${formatUpdateAvailableLine(effectiveCurrent, cachedLatest)}`);
-      console.log('   Run: npm i -g auramaxx --foreground-scripts  (fallback: npx --yes auramaxx@latest start)\n');
+      return { current: effectiveCurrent, latest: cachedLatest };
     }
-    return;
+    return null;
   }
 
   let latest = process.env.AURA_UPDATE_CHECK_MOCK_LATEST || null;
@@ -747,18 +788,18 @@ function maybePrintUpdateNotice() {
 
   if (!latest) {
     try {
-      const out = execFileSync('npm', ['view', 'auramaxx', 'version', '--json'], {
+      const out = execFileSync(resolveNpmCommand(), ['view', 'auramaxx', 'version', '--json'], {
         cwd: root,
         stdio: ['ignore', 'pipe', 'ignore'],
         timeout: Number(process.env.AURA_UPDATE_CHECK_TIMEOUT_MS || '1200'),
       }).toString('utf8').trim();
       latest = JSON.parse(out);
     } catch {
-      return;
+      return null;
     }
   }
   latest = normalizeVersionString(latest);
-  if (!latest) return;
+  if (!latest) return null;
 
   try {
     fs.mkdirSync(path.dirname(cachePath), { recursive: true });
@@ -766,9 +807,91 @@ function maybePrintUpdateNotice() {
   } catch {}
 
   if (latest && compareVersions(latest, current) > 0) {
-    console.log(`\n${formatUpdateAvailableLine(current, latest)}`);
-    console.log('   Run: npm i -g auramaxx --foreground-scripts  (fallback: npx --yes auramaxx@latest start)\n');
+    return { current, latest };
   }
+
+  return null;
+}
+
+function reinstallLatestAuramaxx() {
+  try {
+    execFileSync(resolveNpmCommand(), ['uninstall', '-g', 'auramaxx'], {
+      stdio: 'inherit',
+      timeout: 120000,
+    });
+  } catch {
+    // Ignore uninstall failures for missing or partially-installed global packages.
+  }
+
+  execFileSync(resolveNpmCommand(), ['install', '-g', 'auramaxx@latest', '--foreground-scripts'], {
+    stdio: 'inherit',
+    timeout: 180000,
+  });
+}
+
+function relaunchUpdatedAuramaxx(argv, latestVersion) {
+  const installedVersion = normalizeVersionString(getGlobalInstalledAuramaxxVersion()) || 'unknown';
+  const useNpxLatest = installedVersion === 'unknown' || compareVersions(latestVersion, installedVersion) > 0;
+  const command = useNpxLatest ? 'npx' : resolveAuramaxxCommand();
+  const args = useNpxLatest
+    ? ['--yes', 'auramaxx@latest', ...argv]
+    : argv;
+
+  execFileSync(command, args, {
+    stdio: 'inherit',
+    env: {
+      ...process.env,
+      AURA_NO_UPDATE_CHECK: '1',
+    },
+  });
+  process.exit(0);
+}
+
+async function maybeHandleUpdateNotice() {
+  const update = resolveUpdateNoticeState();
+  if (!update) return;
+
+  const noticeLine = formatUpdateAvailableLine(update.current, update.latest);
+  if (!canPromptForInput()) {
+    console.log(`\n${noticeLine}`);
+    console.log('   Run: npm uninstall -g auramaxx && npm install -g auramaxx --foreground-scripts  (fallback: npx --yes auramaxx@latest start)\n');
+    return;
+  }
+
+  console.log(`\n${noticeLine}`);
+  const choice = await promptSelect(
+    'Update AuraMaxx now?',
+    [
+      { value: 'continue', label: 'No, continue', aliases: ['n', 'no', 'continue', '2'] },
+      { value: 'update', label: 'Yes, update and relaunch', aliases: ['y', 'yes', 'update', '1'] },
+    ],
+    'continue',
+  );
+
+  if (choice !== 'update') {
+    console.log('');
+    return;
+  }
+
+  console.log('');
+  console.log('  Reinstalling latest AuraMaxx...');
+  console.log('');
+
+  try {
+    reinstallLatestAuramaxx();
+  } catch (error) {
+    console.log('');
+    console.error(`  Failed to update AuraMaxx automatically: ${error?.message || String(error)}`);
+    console.error('  Manual fallback: npm uninstall -g auramaxx && npm install -g auramaxx --foreground-scripts');
+    console.error('  Fallback: npx --yes auramaxx@latest start');
+    console.log('');
+    return;
+  }
+
+  console.log('');
+  console.log('  [ok] AuraMaxx updated. Relaunching command...');
+  console.log('');
+  relaunchUpdatedAuramaxx(process.argv.slice(2), update.latest);
 }
 
 function buildRunner(commandName, commandArgs = []) {
@@ -1383,7 +1506,7 @@ async function main() {
     }
   }
 
-  maybePrintUpdateNotice();
+  await maybeHandleUpdateNotice();
   maybeAutoInstallAuraAlias();
   maybeAutoInstallSkills();
   maybeAutoInstallMcp();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "auramaxx",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "AuraJS CLI for creating, playing, and publishing JavaScript-first games.",
   "keywords": [
     "aurajs",
@@ -26,6 +26,8 @@
     "src/lib/startBannerQuotes.ts",
     "src/server/cli/commands/onboard.ts",
     "src/server/cli/commands/create.ts",
+    "src/server/cli/commands/fork.ts",
+    "src/server/cli/commands/make.ts",
     "src/server/cli/commands/play.ts",
     "src/server/cli/commands/publish.ts",
     "src/server/cli/lib/published-game-integrity.ts",

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

@@ -0,0 +1,81 @@
+import { execFileSync } from 'child_process';
+import { rmSync } from 'fs';
+import { pathToFileURL } from 'url';
+
+import { printBanner, printSection, paint, ANSI } from '../lib/theme';
+import {
+  buildPublishedGameLaunchEnv,
+  installVerifiedGamePackage,
+  parseArgs,
+  resolveGameBin,
+  resolvePackageName,
+} from './play';
+
+export interface ForkCommandPlan {
+  help: boolean;
+  name: string | null;
+  gameArgs: string[];
+  gameBin: string | null;
+  packageName: string | null;
+  forwardedArgs: string[];
+}
+
+export function buildForkPlan(argv: string[]): ForkCommandPlan {
+  const parsed = parseArgs(argv);
+  return {
+    ...parsed,
+    gameBin: parsed.name ? resolveGameBin(parsed.name) : null,
+    packageName: parsed.name ? resolvePackageName(parsed.name) : null,
+    forwardedArgs: ['fork', ...parsed.gameArgs],
+  };
+}
+
+export async function main(argv: string[] = process.argv.slice(2)) {
+  const plan = buildForkPlan(argv);
+
+  if (plan.help || !plan.name) {
+    printBanner('FORK');
+    console.log(`  ${paint('Usage:', ANSI.bold)} auramaxx fork <game> [destination|wrapper fork options]`);
+    console.log('');
+    console.log(`  ${paint('Examples:', ANSI.dim)}`);
+    console.log('    auramaxx fork aurasu');
+    console.log('    auramaxx fork aurasu ./aurasu-local');
+    console.log('    auramaxx fork @auraindustry/chess-dev-cli@1.2.3 --dest ./chess-local');
+    console.log('');
+    console.log(`  ${paint('Runs:', ANSI.dim)} verified signed temporary install -> local game wrapper fork`);
+    console.log('');
+    if (!plan.name && !plan.help) {
+      console.error('  Missing game name.');
+      process.exit(1);
+    }
+    return;
+  }
+
+  printBanner(plan.name.toUpperCase());
+  printSection(plan.name, 'Forking editable package into local project...');
+
+  let install: Awaited<ReturnType<typeof installVerifiedGamePackage>> | null = null;
+  try {
+    install = await installVerifiedGamePackage(plan);
+    const env = buildPublishedGameLaunchEnv(process.env);
+    execFileSync(process.execPath, [install.binAbsolutePath, ...plan.forwardedArgs], {
+      stdio: 'inherit',
+      cwd: install.packageRoot,
+      env,
+    });
+  } finally {
+    if (install?.installRoot) {
+      rmSync(install.installRoot, { recursive: true, force: true });
+    }
+  }
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1]).href) {
+  main().catch((err) => {
+    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
+      ?? 1;
+    process.exit(Number.isInteger(status) ? status : 1);
+  });
+}

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

@@ -0,0 +1,90 @@
+import { execFileSync } from 'child_process';
+import { existsSync } from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { printBanner, paint, ANSI } from '../lib/theme';
+
+const COMMAND_DIR = path.dirname(fileURLToPath(import.meta.url));
+const LOCAL_AURAJS_CLI = path.resolve(
+  COMMAND_DIR,
+  '../../../../../packages/aurascript/src/cli/src/cli.mjs',
+);
+
+function parseArgs(argv: string[]) {
+  for (const arg of argv) {
+    if (arg === '--help' || arg === '-h') {
+      return { help: true, passthrough: [] as string[] };
+    }
+  }
+  return {
+    help: false,
+    passthrough: [...argv],
+  };
+}
+
+function resolveInvocationCwd(): string {
+  const forwardedCwd = process.env.AURA_INVOKE_CWD;
+  if (forwardedCwd && path.isAbsolute(forwardedCwd)) {
+    return forwardedCwd;
+  }
+
+  const shellPwd = process.env.PWD;
+  if (shellPwd && path.isAbsolute(shellPwd)) {
+    return shellPwd;
+  }
+  return process.cwd();
+}
+
+async function main() {
+  const parsed = parseArgs(process.argv.slice(2));
+
+  if (parsed.help) {
+    printBanner('MAKE');
+    console.log(`  ${paint('Usage:', ANSI.bold)} auramaxx make [kind] [name] [--role <custom|enemy|pickup|player|world>]`);
+    console.log('');
+    console.log('  Public wrapper around AuraJS project file generation.');
+    console.log('  Run it from inside an AuraJS game project.');
+    console.log(`  ${paint('Examples:', ANSI.dim)}`);
+    console.log('    auramaxx make');
+    console.log('    auramaxx make scene Scene1');
+    console.log('    auramaxx make ui-screen PauseMenu');
+    console.log('    auramaxx make prefab EnemyShip --role enemy');
+    console.log('    auramaxx make list');
+    console.log('');
+    console.log('  When no arguments are passed in a TTY, AuraJS opens an interactive make flow.');
+    console.log('');
+    return;
+  }
+
+  const invocationCwd = resolveInvocationCwd();
+  const auraArgs = ['make', ...parsed.passthrough];
+
+  try {
+    if (existsSync(LOCAL_AURAJS_CLI)) {
+      execFileSync(process.execPath, [LOCAL_AURAJS_CLI, ...auraArgs], {
+        cwd: invocationCwd,
+        stdio: 'inherit',
+        env: process.env,
+      });
+    } else {
+      execFileSync(
+        'npm',
+        ['exec', '--yes', '--package', '@auraindustry/aurajs', '--', 'aura', ...auraArgs],
+        {
+          cwd: invocationCwd,
+          stdio: 'inherit',
+          env: process.env,
+        },
+      );
+    }
+  } catch (error: unknown) {
+    const status = (error as { status?: number }).status;
+    if (status) process.exit(status);
+    throw error;
+  }
+}
+
+main().catch((err) => {
+  console.error(err instanceof Error ? err.message : String(err));
+  process.exit(1);
+});

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

@@ -6,6 +6,7 @@ import { pathToFileURL } from 'url';
 import { printBanner, printSection, paint, ANSI, createProgressDisplay, printComplete } from '../lib/theme';
 import { promptSelect } from '../lib/prompt';
 import { PublishedGameIntegrityError } from '../lib/published-game-integrity';
+import { resolveAuraJsProjectRoot, resolveInvocationCwd, delegateToAuraJsCommand } from '../lib/aurajs-project';
 import {
   assertPublishedGameBinIntegrity,
   buildPublishedGameLaunchEnv,
@@ -114,6 +115,27 @@ function resolveAuramaxxCommand(): string {
   return process.platform === 'win32' ? 'auramaxx.cmd' : 'auramaxx';
 }
 
+function resolveInstalledGlobalAuramaxxVersion(): string | null {
+  try {
+    const root = execFileSync(resolveNpmCommand(), ['root', '-g'], {
+      stdio: ['ignore', 'pipe', 'pipe'],
+      encoding: 'utf8',
+      timeout: 30000,
+    }).trim();
+    if (!root) {
+      return null;
+    }
+    const packageJsonPath = join(root, 'auramaxx', 'package.json');
+    if (!existsSync(packageJsonPath)) {
+      return null;
+    }
+    const pkg = JSON.parse(readFileSync(packageJsonPath, 'utf8')) as { version?: unknown };
+    return typeof pkg.version === 'string' && pkg.version.trim().length > 0 ? pkg.version.trim() : null;
+  } catch {
+    return null;
+  }
+}
+
 function normalizeRelativePath(pathLike: string): string {
   return String(pathLike || '')
     .trim()
@@ -212,12 +234,26 @@ async function promptUpgradeAuramaxx(expectedAurajsVersion: string): Promise<boo
 
 function installLatestAuramaxx(): void {
   console.log('');
-  console.log(`  ${paint('Installing latest AuraMaxx...', ANSI.bold)}`);
+  console.log(`  ${paint('Reinstalling latest AuraMaxx...', ANSI.bold)}`);
   console.log('');
+  try {
+    execFileSync(resolveNpmCommand(), ['uninstall', '-g', 'auramaxx'], {
+      stdio: 'inherit',
+      timeout: 120000,
+    });
+  } catch {
+    // Ignore missing-package uninstall failures and continue with a clean install.
+  }
   execFileSync(resolveNpmCommand(), ['install', '-g', 'auramaxx@latest', '--foreground-scripts'], {
     stdio: 'inherit',
-    timeout: 120000,
+    timeout: 180000,
   });
+
+  const installedVersion = resolveInstalledGlobalAuramaxxVersion();
+  if (installedVersion) {
+    console.log('');
+    console.log(`  ${paint(`Installed AuraMaxx ${installedVersion}`, ANSI.dim)}`);
+  }
 }
 
 function relaunchWithUpdatedAuramaxx(argv: string[]): never {
@@ -330,6 +366,12 @@ function describeForwardedCommand(command: string): string {
 
 export async function main(argv: string[] = process.argv.slice(2)) {
   const plan = buildPlayPlan(argv);
+  const invocationCwd = resolveInvocationCwd();
+  const auraJsProjectRoot = resolveAuraJsProjectRoot(invocationCwd);
+
+  if (!plan.name && auraJsProjectRoot) {
+    delegateToAuraJsCommand(['play', ...argv], auraJsProjectRoot);
+  }
 
   if (plan.help || !plan.name) {
     printBanner('PLAY');
@@ -400,7 +442,7 @@ if (import.meta.url === pathToFileURL(process.argv[1]).href) {
               ? updateError.message
               : String(updateError),
           );
-          console.error('  Manual fallback: npm install -g auramaxx@latest');
+          console.error('  Manual fallback: npm uninstall -g auramaxx && npm install -g auramaxx@latest');
           process.exit(1);
         }
       })().catch((promptError) => {

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

@@ -1,6 +1,7 @@
 import { execFileSync } from 'child_process';
 import { existsSync, readFileSync, writeFileSync } from 'fs';
 import path from 'path';
+import { fileURLToPath } from 'url';
 import { printBanner, printSection, printStatus, paint, ANSI } from '../lib/theme';
 import { promptInput, promptSelect } from '../lib/prompt';
 
@@ -19,6 +20,11 @@ interface ParsedArgs {
 const SEMVER_RE = /^v?(\d+)\.(\d+)\.(\d+)(-[0-9A-Za-z-.]+)?$/;
 const SCOPED_PACKAGE_RE = /^@[a-z0-9][a-z0-9._-]*\/[a-z0-9][a-z0-9._-]*$/;
 const UNSCOPED_PACKAGE_RE = /^[a-z0-9][a-z0-9._-]*$/;
+const COMMAND_DIR = path.dirname(fileURLToPath(import.meta.url));
+const LOCAL_AURAJS_CLI = path.resolve(
+  COMMAND_DIR,
+  '../../../../../packages/aurascript/src/cli/src/cli.mjs',
+);
 
 function parseArgs(argv: string[]): ParsedArgs {
   const parsed: ParsedArgs = {
@@ -100,6 +106,52 @@ function resolveInvocationCwd(): string {
   return process.cwd();
 }
 
+function resolveAuraJsProjectRoot(startDir: string): string | null {
+  let current = path.resolve(startDir);
+
+  while (true) {
+    const auraConfigPath = path.join(current, 'aura.config.json');
+    const packageJsonPath = path.join(current, 'package.json');
+    if (existsSync(auraConfigPath) && existsSync(packageJsonPath)) {
+      return current;
+    }
+
+    const parent = path.dirname(current);
+    if (parent === current) break;
+    current = parent;
+  }
+
+  return null;
+}
+
+function delegateToAuraJsPublish(rawArgs: string[], projectRoot: string): never {
+  const auraArgs = ['publish', ...rawArgs];
+
+  try {
+    if (existsSync(LOCAL_AURAJS_CLI)) {
+      execFileSync(process.execPath, [LOCAL_AURAJS_CLI, ...auraArgs], {
+        cwd: projectRoot,
+        stdio: 'inherit',
+        env: process.env,
+      });
+    } else {
+      execFileSync(
+        'npm',
+        ['exec', '--yes', '--package', '@auraindustry/aurajs', '--', 'aura', ...auraArgs],
+        {
+          cwd: projectRoot,
+          stdio: 'inherit',
+          env: process.env,
+        },
+      );
+    }
+    process.exit(0);
+  } catch (error: unknown) {
+    const status = (error as { status?: number }).status;
+    process.exit(status || 1);
+  }
+}
+
 function sanitizePackageSlug(value: string): string {
   const compact = String(value || '')
     .trim()
@@ -253,8 +305,15 @@ async function resolveVersion(options: {
 }
 
 async function main() {
-  const parsed = parseArgs(process.argv.slice(2));
   const invocationCwd = resolveInvocationCwd();
+  const rawArgs = process.argv.slice(2);
+  const auraJsProjectRoot = resolveAuraJsProjectRoot(invocationCwd);
+
+  if (auraJsProjectRoot) {
+    delegateToAuraJsPublish(rawArgs, auraJsProjectRoot);
+  }
+
+  const parsed = parseArgs(rawArgs);
   const packageJsonPath = path.join(invocationCwd, 'package.json');
 
   if (parsed.help) {