auramaxx 0.1.3 → 0.1.5

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 = []) {
@@ -1317,8 +1440,7 @@ async function main() {
 
   const inferredStartFlags = new Set(['--debug', '--terminal', '--headless', '--background', '--daemon', '-d']);
   if (cmd && inferredStartFlags.has(cmd)) {
-    const defaultCommand = resolveDefaultCommand();
-    if (defaultCommand === 'start') {
+    if (isCommandAvailable('start')) {
       inferredCommand = true;
       args.unshift(cmd);
       cmd = 'start';
@@ -1383,7 +1505,7 @@ async function main() {
     }
   }
 
-  maybePrintUpdateNotice();
+  await maybeHandleUpdateNotice();
   maybeAutoInstallAuraAlias();
   maybeAutoInstallSkills();
   maybeAutoInstallMcp();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "auramaxx",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "AuraJS CLI for creating, playing, and publishing JavaScript-first games.",
   "keywords": [
     "aurajs",
@@ -30,6 +30,7 @@
     "src/server/cli/commands/make.ts",
     "src/server/cli/commands/play.ts",
     "src/server/cli/commands/publish.ts",
+    "src/server/cli/lib/aurajs-project.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/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,
@@ -365,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');

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) {

package/src/server/cli/lib/aurajs-project.ts

@@ -0,0 +1,84 @@
+import { execFileSync } from 'child_process';
+import { existsSync } from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const LIB_DIR = path.dirname(fileURLToPath(import.meta.url));
+export const LOCAL_AURAJS_CLI = path.resolve(
+  LIB_DIR,
+  '../../../../../packages/aurascript/src/cli/src/cli.mjs',
+);
+
+export 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();
+}
+
+export 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;
+}
+
+export function requireAuraJsProjectRoot(startDir: string): string {
+  const projectRoot = resolveAuraJsProjectRoot(startDir);
+  if (projectRoot) {
+    return projectRoot;
+  }
+
+  throw new Error('Not an AuraJS project. Run `auramaxx create my-game` first.');
+}
+
+export function delegateToAuraJsCommand(auraArgs: string[], cwd: string): never {
+  try {
+    if (existsSync(LOCAL_AURAJS_CLI)) {
+      execFileSync(process.execPath, [LOCAL_AURAJS_CLI, ...auraArgs], {
+        cwd,
+        stdio: 'inherit',
+        env: process.env,
+      });
+    } else {
+      execFileSync(
+        'npm',
+        ['exec', '--yes', '--package', '@auraindustry/aurajs', '--', 'aura', ...auraArgs],
+        {
+          cwd,
+          stdio: 'inherit',
+          env: process.env,
+        },
+      );
+    }
+
+    process.exit(0);
+  } catch (error: unknown) {
+    const status = (error as { status?: number }).status;
+    process.exit(status || 1);
+  }
+}
+
+export function delegateToAuraJsProjectCommand(commandName: string, commandArgs: string[] = []): never {
+  const invocationCwd = resolveInvocationCwd();
+  const projectRoot = requireAuraJsProjectRoot(invocationCwd);
+  delegateToAuraJsCommand([commandName, ...commandArgs], projectRoot);
+}