@auraindustry/aurajs 0.0.2 → 0.0.4

package/src/react/aura-game.mjs

@@ -0,0 +1,310 @@
+import React, { useEffect, useMemo, useRef, useState } from 'react';
+
+import { createAuraGame } from '../web-api.mjs';
+
+function isPlainObject(value) {
+  return value != null && typeof value === 'object' && Object.prototype.toString.call(value) === '[object Object]';
+}
+
+function stableSerialize(value) {
+  if (value == null) return 'null';
+  if (typeof value === 'boolean' || typeof value === 'number') return JSON.stringify(value);
+  if (typeof value === 'string') return JSON.stringify(value);
+  if (Array.isArray(value)) {
+    return '[' + value.map((entry) => stableSerialize(entry)).join(',') + ']';
+  }
+  if (isPlainObject(value)) {
+    const keys = Object.keys(value).sort();
+    const fields = [];
+    for (const key of keys) {
+      fields.push(JSON.stringify(key) + ':' + stableSerialize(value[key]));
+    }
+    return '{' + fields.join(',') + '}';
+  }
+  return JSON.stringify(String(value));
+}
+
+function createReactError(reasonCode, message, retryable, details) {
+  const error = new Error(message);
+  error.ok = false;
+  error.reasonCode = reasonCode;
+  error.layer = 'react';
+  error.retryable = retryable === true;
+  error.details = isPlainObject(details) ? { ...details } : {};
+  return error;
+}
+
+function normalizeReasonCodedError(error, fallbackReasonCode, fallbackMessage, fallbackRetryable) {
+  if (error && typeof error === 'object' && typeof error.reasonCode === 'string') {
+    return error;
+  }
+  return createReactError(
+    fallbackReasonCode,
+    fallbackMessage,
+    fallbackRetryable,
+    { cause: String(error && error.message ? error.message : error) },
+  );
+}
+
+function stableErrorKey(error) {
+  if (!error || typeof error !== 'object') return null;
+  return stableSerialize({
+    reasonCode: typeof error.reasonCode === 'string' ? error.reasonCode : null,
+    layer: typeof error.layer === 'string' ? error.layer : null,
+    retryable: error.retryable === true,
+    details: isPlainObject(error.details) ? error.details : {},
+  });
+}
+
+function normalizeSource(source) {
+  if (source == null) return '.';
+  if (typeof source !== 'string' || source.trim().length === 0) {
+    throw createReactError(
+      'react_auragame_invalid_source',
+      'AuraGame prop source must be a non-empty string.',
+      false,
+      {},
+    );
+  }
+  return source.trim();
+}
+
+function normalizeConfig(config) {
+  if (config == null) return {};
+  if (!isPlainObject(config)) {
+    throw createReactError(
+      'react_auragame_invalid_config',
+      'AuraGame prop config must be a plain object.',
+      false,
+      {},
+    );
+  }
+  return { ...config };
+}
+
+async function safeUnmount(game) {
+  if (!game || typeof game.unmount !== 'function') return;
+  try {
+    await game.unmount();
+  } catch (_) {
+    // Cleanup should not throw through React unmount paths.
+  }
+}
+
+export function AuraGame(props = {}) {
+  const {
+    source = '.',
+    config = null,
+    restartKey = null,
+    loader = null,
+    className,
+    style,
+    mountClassName,
+    mountStyle,
+    onReady,
+    onPhaseChange,
+    onLifecycle,
+    onLoadingChange,
+    onError,
+    renderLoading,
+    renderError,
+  } = props;
+
+  const mountNodeRef = useRef(null);
+  const gameRef = useRef(null);
+  const callbacksRef = useRef({
+    onReady: null,
+    onPhaseChange: null,
+    onLifecycle: null,
+    onLoadingChange: null,
+    onError: null,
+  });
+  callbacksRef.current = {
+    onReady: typeof onReady === 'function' ? onReady : null,
+    onPhaseChange: typeof onPhaseChange === 'function' ? onPhaseChange : null,
+    onLifecycle: typeof onLifecycle === 'function' ? onLifecycle : null,
+    onLoadingChange: typeof onLoadingChange === 'function' ? onLoadingChange : null,
+    onError: typeof onError === 'function' ? onError : null,
+  };
+
+  const [phase, setPhase] = useState('idle');
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState(null);
+  const loadingRef = useRef(false);
+  const lastErrorKeyRef = useRef(null);
+
+  const configSignature = useMemo(() => stableSerialize(config), [config]);
+  const restartSignature = useMemo(
+    () => stableSerialize({ source, config: configSignature, restartKey }),
+    [source, configSignature, restartKey],
+  );
+
+  function setLoadingState(nextLoading) {
+    const next = nextLoading === true;
+    if (loadingRef.current === next) return;
+    loadingRef.current = next;
+    setLoading(next);
+    if (callbacksRef.current.onLoadingChange) {
+      callbacksRef.current.onLoadingChange(next);
+    }
+  }
+
+  function emitError(nextError, stateSnapshot) {
+    const normalized = normalizeReasonCodedError(
+      nextError,
+      'react_auragame_mount_failed',
+      'Failed to mount AuraGame.',
+      true,
+    );
+    const key = stableErrorKey(normalized);
+    if (key === lastErrorKeyRef.current) {
+      return normalized;
+    }
+    lastErrorKeyRef.current = key;
+    setError(normalized);
+    if (callbacksRef.current.onError) {
+      callbacksRef.current.onError(normalized, stateSnapshot || null);
+    }
+    return normalized;
+  }
+
+  useEffect(() => {
+    let cancelled = false;
+    const mountNode = mountNodeRef.current;
+    if (!mountNode) {
+      const mountError = createReactError(
+        'react_auragame_mount_node_missing',
+        'AuraGame mount node is unavailable.',
+        false,
+        {},
+      );
+      setPhase('error');
+      setLoadingState(false);
+      emitError(mountError, { phase: 'error', reasonCode: mountError.reasonCode });
+      return () => {};
+    }
+
+    let normalizedSource = '.';
+    let normalizedConfig = {};
+    try {
+      normalizedSource = normalizeSource(source);
+      normalizedConfig = normalizeConfig(config);
+    } catch (validationError) {
+      setPhase('error');
+      setLoadingState(false);
+      emitError(validationError, { phase: 'error', reasonCode: validationError.reasonCode });
+      return () => {};
+    }
+
+    setPhase('idle');
+    setError(null);
+    lastErrorKeyRef.current = null;
+    setLoadingState(true);
+
+    const game = createAuraGame({
+      loader,
+      onPhaseChange: (nextPhase, stateSnapshot) => {
+        if (cancelled) return;
+        setPhase(typeof nextPhase === 'string' ? nextPhase : 'idle');
+        if (callbacksRef.current.onPhaseChange) {
+          callbacksRef.current.onPhaseChange(nextPhase, stateSnapshot);
+        }
+      },
+      onLifecycle: (lifecycle, stateSnapshot) => {
+        if (cancelled) return;
+        if (callbacksRef.current.onLifecycle) {
+          callbacksRef.current.onLifecycle(lifecycle, stateSnapshot);
+        }
+      },
+      onError: (nextError, stateSnapshot) => {
+        if (cancelled) return;
+        setPhase('error');
+        emitError(nextError, stateSnapshot);
+      },
+    });
+    gameRef.current = game;
+
+    async function start() {
+      try {
+        game.setConfig({
+          ...normalizedConfig,
+          rootUrl: normalizedSource,
+          mount: mountNode,
+        });
+        const mountedState = await game.mount(mountNode, {
+          ...normalizedConfig,
+          rootUrl: normalizedSource,
+          mount: mountNode,
+        });
+        if (cancelled) {
+          await safeUnmount(game);
+          return;
+        }
+        setPhase(typeof mountedState.phase === 'string' ? mountedState.phase : 'mounted');
+        setError(null);
+        setLoadingState(false);
+        if (callbacksRef.current.onReady) {
+          callbacksRef.current.onReady(mountedState);
+        }
+      } catch (mountError) {
+        if (cancelled) return;
+        const normalized = normalizeReasonCodedError(
+          mountError,
+          'react_auragame_mount_failed',
+          'Failed to mount AuraGame.',
+          true,
+        );
+        setPhase('error');
+        setLoadingState(false);
+        emitError(normalized, { phase: 'error', reasonCode: normalized.reasonCode });
+      }
+    }
+
+    void start();
+
+    return () => {
+      cancelled = true;
+      if (gameRef.current === game) {
+        gameRef.current = null;
+      }
+      void safeUnmount(game);
+    };
+  }, [loader, restartSignature]);
+
+  const children = [
+    React.createElement('div', {
+      key: 'mount',
+      ref: mountNodeRef,
+      className: mountClassName,
+      style: mountStyle,
+      'data-aura-game-mount': 'true',
+    }),
+  ];
+
+  if (loading && typeof renderLoading === 'function') {
+    children.push(React.createElement(React.Fragment, { key: 'loading' }, renderLoading({
+      phase,
+      loading,
+      error,
+    })));
+  }
+
+  if (error && typeof renderError === 'function') {
+    children.push(React.createElement(React.Fragment, { key: 'error' }, renderError(error, {
+      phase,
+      loading,
+      error,
+    })));
+  }
+
+  return React.createElement('div', {
+    className,
+    style,
+    'data-aura-game': 'true',
+    'data-aura-phase': phase,
+    'data-aura-loading': loading ? 'true' : 'false',
+    'data-aura-error-code': error && typeof error.reasonCode === 'string' ? error.reasonCode : '',
+  }, children);
+}
+
+export default AuraGame;

package/src/react/index.mjs

@@ -0,0 +1 @@
+export { AuraGame, default } from './aura-game.mjs';

package/src/scaffold.mjs

@@ -2,36 +2,290 @@ import { mkdirSync, writeFileSync, readFileSync, existsSync, readdirSync, statSy
 import { resolve, join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
-const TEMPLATES_DIR = resolve(
-  dirname(fileURLToPath(import.meta.url)),
-  '../templates/starter'
-);
+const CLI_SRC_DIR = dirname(fileURLToPath(import.meta.url));
+
+const LEGACY_STARTER_TEMPLATE_DIR = resolve(CLI_SRC_DIR, '../templates/starter');
+
+const CREATE_TEMPLATE_DIRS = {
+  '2d-shooter': resolve(CLI_SRC_DIR, '../templates/create/2d'),
+  '3d-platformer': resolve(CLI_SRC_DIR, '../templates/create/3d'),
+  blank: resolve(CLI_SRC_DIR, '../templates/create/blank'),
+};
+const CREATE_SHARED_TEMPLATE_DIR = resolve(CLI_SRC_DIR, '../templates/create/shared');
+
+const CREATE_TEMPLATE_ALIASES = {
+  '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 platformers': '3d-platformer',
+  '3d-platformer': '3d-platformer',
+  blank: 'blank',
+};
+
+const ROOT_SKILLS_DIR = resolve(CLI_SRC_DIR, '../../../skills');
+const PACKAGED_SKILLS_DIR = resolve(CLI_SRC_DIR, '../templates/skills');
+
+const GITIGNORE_TEMPLATE = `# Dependencies\nnode_modules/\n\n# Build output\nbuild/\n.aura/\n\n# Runtime logs\n.logs/\n*.log\nnpm-debug.log*\n\n# Local env\n.env\n.env.*\n`;
+
+const PLAY_BIN_TEMPLATE = `#!/usr/bin/env node
+
+import { spawn } from 'node:child_process';
+import { existsSync, mkdirSync, createWriteStream } from 'node:fs';
+import { resolve, dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const projectRoot = resolve(__dirname, '..');
+const localAuraCli = resolve(projectRoot, 'node_modules', '@auraindustry', 'aurajs', 'src', 'cli.mjs');
+const runArgs = ['run', '--asset-mode', 'sibling'];
+
+const logDir = resolve(projectRoot, '.logs');
+mkdirSync(logDir, { recursive: true });
+const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+const logPath = join(logDir, \`play-\${stamp}.log\`);
+const logStream = createWriteStream(logPath, { flags: 'a' });
+
+const command = existsSync(localAuraCli)
+  ? {
+      cmd: process.execPath,
+      args: [localAuraCli, ...runArgs],
+    }
+  : {
+      cmd: 'npm',
+      args: ['exec', '--yes', '--package', '@auraindustry/aurajs', '--', 'aura', ...runArgs],
+    };
+
+logStream.write(\`[play] \${new Date().toISOString()} command=\${command.cmd} \${command.args.join(' ')}\\n\`);
+
+const child = spawn(command.cmd, command.args, {
+  cwd: projectRoot,
+  stdio: ['inherit', 'pipe', 'pipe'],
+  env: process.env,
+});
+
+function pipeToConsoleAndLog(stream, target) {
+  if (!stream) return;
+  stream.on('data', (chunk) => {
+    target.write(chunk);
+    logStream.write(chunk);
+  });
+}
+
+pipeToConsoleAndLog(child.stdout, process.stdout);
+pipeToConsoleAndLog(child.stderr, process.stderr);
+
+child.on('error', (err) => {
+  const message = \`[play:error] \${err.message}\\n\`;
+  process.stderr.write(message);
+  logStream.write(message);
+  logStream.end();
+  process.exit(1);
+});
+
+child.on('close', (code) => {
+  logStream.write(\`\\n[play:exit] code=\${code ?? 1}\\n\`);
+  logStream.end(() => {
+    process.exit(code ?? 1);
+  });
+});
+`;
+
+export function listCreateTemplates() {
+  return Object.keys(CREATE_TEMPLATE_DIRS);
+}
+
+export function normalizeCreateTemplate(template) {
+  const normalized = String(template || '').trim().toLowerCase();
+  return CREATE_TEMPLATE_ALIASES[normalized] || null;
+}
 
 /**
- * Scaffold a new AuraJS project.
+ * Scaffold the legacy starter template (`aura init`).
  * @param {string} name - Project name (used as directory name and in config).
  * @param {string} dest - Absolute path to create the project at.
  */
 export function scaffold(name, dest) {
-  if (existsSync(dest)) {
-    const entries = readdirSync(dest);
-    if (entries.length > 0) {
-      throw new Error(`Directory "${name}" already exists and is not empty.`);
-    }
+  assertDestinationIsEmpty(name, dest);
+
+  copyTree(LEGACY_STARTER_TEMPLATE_DIR, dest, { PROJECT_NAME: name });
+  mkdirSync(join(dest, 'assets'), { recursive: true });
+
+  return {
+    dest,
+    files: listFiles(dest),
+  };
+}
+
+/**
+ * Scaffold a full npm-ready AuraJS game project (`aura create`).
+ * @param {object} options - Scaffolding options.
+ * @param {string} options.name - Project directory name (npm package defaults to @aurajs/<name>).
+ * @param {string} options.dest - Absolute destination directory.
+ * @param {string} [options.template='2d-shooter'] - Template key: 2d-shooter | 3d-platformer | blank.
+ * @param {string} [options.version='0.1.0'] - Initial package version.
+ * @param {string} [options.license='MIT'] - Initial package license.
+ */
+export function scaffoldGame(options) {
+  const {
+    name,
+    dest,
+    template = '2d-shooter',
+    version = '0.1.0',
+    license = 'MIT',
+  } = options;
+
+  const normalizedTemplate = normalizeCreateTemplate(template);
+  const templateDir = CREATE_TEMPLATE_DIRS[normalizedTemplate];
+  if (!templateDir || !existsSync(templateDir)) {
+    throw new Error(
+      `Unknown template "${template}". Expected one of: ${listCreateTemplates().join(', ')} (aliases: 2d, 3d, shooter, platformer, blank).`,
+    );
   }
 
-  // Copy template tree, replacing {{PROJECT_NAME}} placeholders.
-  copyTree(TEMPLATES_DIR, dest, { PROJECT_NAME: name });
+  assertDestinationIsEmpty(name, dest);
+
+  const binName = sanitizeBinName(name);
+  const projectTitle = toDisplayTitle(name);
+  const replacements = {
+    PROJECT_NAME: name,
+    PROJECT_TITLE: projectTitle,
+    PROJECT_BIN_NAME: binName,
+    PROJECT_VERSION: version,
+    PROJECT_LICENSE: license,
+  };
+
+  copyTree(templateDir, dest, replacements);
+  if (normalizedTemplate !== 'blank' && existsSync(CREATE_SHARED_TEMPLATE_DIR)) {
+    copyTree(CREATE_SHARED_TEMPLATE_DIR, dest, replacements);
+  }
 
-  // Ensure assets/ directory exists (even if empty in template).
   mkdirSync(join(dest, 'assets'), { recursive: true });
+  mkdirSync(join(dest, 'bin'), { recursive: true });
+  mkdirSync(join(dest, '.logs'), { recursive: true });
+  writeFileSync(join(dest, '.logs', '.gitkeep'), '', 'utf8');
+
+  const pkg = buildPackageJson({
+    name,
+    version,
+    license,
+    binName,
+    template: normalizedTemplate,
+  });
+
+  writeFileSync(join(dest, 'package.json'), JSON.stringify(pkg, null, 2) + '\n', 'utf8');
+  writeFileSync(join(dest, '.gitignore'), GITIGNORE_TEMPLATE, 'utf8');
+  writeFileSync(join(dest, 'bin', 'play.js'), PLAY_BIN_TEMPLATE, { encoding: 'utf8', mode: 0o755 });
+
+  const skillsSource = resolveSkillsSourceDir();
+  if (skillsSource) {
+    copyTree(skillsSource, join(dest, 'skills'), replacements);
+  } else {
+    mkdirSync(join(dest, 'skills'), { recursive: true });
+  }
 
   return {
     dest,
+    template: normalizedTemplate,
     files: listFiles(dest),
   };
 }
 
+function sanitizeBinName(name) {
+  const normalized = String(name || '').trim();
+  const compact = normalized
+    .replace(/^@[^/]+\//, '')
+    .replace(/\s+/g, '-')
+    .replace(/[^a-zA-Z0-9._-]/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/^[-._]+|[-._]+$/g, '')
+    .toLowerCase();
+
+  if (!compact) {
+    throw new Error(`Unable to derive executable name from project name "${name}".`);
+  }
+
+  return compact;
+}
+
+function sanitizePackageSlug(name) {
+  const normalized = String(name || '').trim();
+  const compact = normalized
+    .replace(/^@[^/]+\//, '')
+    .replace(/\s+/g, '-')
+    .replace(/[^a-zA-Z0-9._-]/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/^[-._]+|[-._]+$/g, '')
+    .toLowerCase();
+
+  if (!compact) {
+    throw new Error(`Unable to derive package slug from project name "${name}".`);
+  }
+
+  return compact;
+}
+
+function toDisplayTitle(name) {
+  const cleaned = String(name || '').replace(/^@[^/]+\//, '');
+  const words = cleaned.split(/[-_\s]+/).filter(Boolean);
+  if (words.length === 0) return String(name || '').trim() || 'AuraJS Game';
+  return words.map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join(' ');
+}
+
+function resolveSkillsSourceDir() {
+  if (existsSync(ROOT_SKILLS_DIR)) return ROOT_SKILLS_DIR;
+  if (existsSync(PACKAGED_SKILLS_DIR)) return PACKAGED_SKILLS_DIR;
+  return null;
+}
+
+function buildPackageJson({ name, version, license, binName, template }) {
+  const packageSlug = sanitizePackageSlug(name);
+  const packageName = `@aurajs/${packageSlug}`;
+  const keywords = ['aurajs', 'game'];
+  if (template.includes('3d')) {
+    keywords.push('3d');
+    keywords.push('platformer');
+  } else if (template.includes('2d')) {
+    keywords.push('2d');
+    keywords.push('shooter');
+  }
+
+  return {
+    name: packageName,
+    version,
+    description: `${toDisplayTitle(name)} — built with AuraJS`,
+    type: 'module',
+    bin: {
+      [binName]: './bin/play.js',
+    },
+    files: ['bin/', 'src/', 'assets/', 'skills/', 'aura.config.json'],
+    scripts: {
+      dev: 'aura dev',
+      build: 'aura build',
+      play: 'node ./bin/play.js',
+      publish: 'npx auramaxx publish',
+    },
+    dependencies: {
+      '@auraindustry/aurajs': '*',
+    },
+    keywords,
+    license,
+  };
+}
+
+function assertDestinationIsEmpty(name, dest) {
+  if (existsSync(dest)) {
+    const entries = readdirSync(dest);
+    if (entries.length > 0) {
+      throw new Error(`Directory "${name}" already exists and is not empty.`);
+    }
+  }
+}
+
 /**
  * Recursively copy a directory tree, applying placeholder replacements
  * to text files.