@auraindustry/aurajs 0.0.7 → 0.1.0

package/src/retro/emulator/profiles.mjs

@@ -0,0 +1,146 @@
+import { basename } from 'node:path';
+
+const ALL_RETRO_TARGETS = Object.freeze(['gb', 'gbc', 'gba']);
+
+export const RETRO_EMULATOR_PROFILES = Object.freeze([
+  Object.freeze({
+    id: 'mgba-headless',
+    commandNames: Object.freeze(['mgba-headless']),
+    supportedTargets: ALL_RETRO_TARGETS,
+    supportsHeadless: true,
+    preferForSmoke: true,
+    launchArgs: ({ romPath, scale }) => {
+      const args = [];
+      if (Number.isFinite(scale) && scale > 0) {
+        args.push('--scale', String(scale));
+      }
+      args.push(romPath);
+      return args;
+    },
+    smokeArgs: ({ romPath, scale }) => {
+      const args = [];
+      if (Number.isFinite(scale) && scale > 0) {
+        args.push('--scale', String(scale));
+      }
+      args.push(romPath);
+      return args;
+    },
+  }),
+  Object.freeze({
+    id: 'mgba',
+    commandNames: Object.freeze(['mgba']),
+    supportedTargets: ALL_RETRO_TARGETS,
+    supportsHeadless: false,
+    preferForSmoke: false,
+    launchArgs: ({ romPath, scale }) => {
+      const args = [];
+      if (Number.isFinite(scale) && scale > 0) {
+        args.push('--scale', String(scale));
+      }
+      args.push(romPath);
+      return args;
+    },
+    smokeArgs: ({ romPath, scale }) => {
+      const args = [];
+      if (Number.isFinite(scale) && scale > 0) {
+        args.push('--scale', String(scale));
+      }
+      args.push(romPath);
+      return args;
+    },
+  }),
+  Object.freeze({
+    id: 'mgba-qt',
+    commandNames: Object.freeze(['mgba-qt']),
+    supportedTargets: ALL_RETRO_TARGETS,
+    supportsHeadless: false,
+    preferForSmoke: false,
+    launchArgs: ({ romPath, scale }) => {
+      const args = [];
+      if (Number.isFinite(scale) && scale > 0) {
+        args.push('--scale', String(scale));
+      }
+      args.push(romPath);
+      return args;
+    },
+    smokeArgs: ({ romPath, scale }) => {
+      const args = [];
+      if (Number.isFinite(scale) && scale > 0) {
+        args.push('--scale', String(scale));
+      }
+      args.push(romPath);
+      return args;
+    },
+  }),
+  Object.freeze({
+    id: 'visualboyadvance-m',
+    commandNames: Object.freeze(['visualboyadvance-m']),
+    supportedTargets: ALL_RETRO_TARGETS,
+    supportsHeadless: false,
+    preferForSmoke: false,
+    launchArgs: ({ romPath }) => [romPath],
+    smokeArgs: ({ romPath }) => [romPath],
+  }),
+  Object.freeze({
+    id: 'sameboy',
+    commandNames: Object.freeze(['sameboy']),
+    supportedTargets: Object.freeze(['gb', 'gbc']),
+    supportsHeadless: false,
+    preferForSmoke: false,
+    launchArgs: ({ romPath }) => [romPath],
+    smokeArgs: ({ romPath }) => [romPath],
+  }),
+]);
+
+function normalizeExecutableName(value) {
+  return basename(String(value || '')).toLowerCase();
+}
+
+export function getRetroEmulatorProfile(profileId) {
+  return RETRO_EMULATOR_PROFILES.find((entry) => entry.id === profileId) || null;
+}
+
+export function detectRetroEmulatorProfile(executablePath) {
+  const name = normalizeExecutableName(executablePath);
+  for (const profile of RETRO_EMULATOR_PROFILES) {
+    if (profile.commandNames.includes(name)) {
+      return profile;
+    }
+  }
+  return null;
+}
+
+export function getRetroEmulatorCandidateNames({ target, smoke = false } = {}) {
+  const names = [];
+  for (const profile of RETRO_EMULATOR_PROFILES) {
+    if (!profile.supportedTargets.includes(target)) {
+      continue;
+    }
+    if (smoke && !profile.supportsHeadless) {
+      continue;
+    }
+    for (const commandName of profile.commandNames) {
+      if (!names.includes(commandName)) {
+        names.push(commandName);
+      }
+    }
+  }
+  return names;
+}
+
+export function supportsRetroEmulatorTarget(profile, target) {
+  return Array.isArray(profile?.supportedTargets) && profile.supportedTargets.includes(target);
+}
+
+export function buildRetroEmulatorArgs(profile, { romPath, smoke = false, headless = false, scale = null }) {
+  if (!profile) {
+    return [romPath];
+  }
+  if (smoke && typeof profile.smokeArgs === 'function') {
+    return profile.smokeArgs({ romPath, headless, scale });
+  }
+  if (!smoke && typeof profile.launchArgs === 'function') {
+    return profile.launchArgs({ romPath, headless, scale });
+  }
+  return [romPath];
+}

package/src/retro/emulator/runner.mjs

@@ -0,0 +1,289 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { basename, extname, resolve } from 'node:path';
+import { spawn } from 'node:child_process';
+import { RetroCompileError } from '../diagnostics/emit.mjs';
+import { discoverRetroEmulator } from './discovery.mjs';
+import { launchRetroCaseOverlay, shouldUseRetroCaseOverlay } from './case-overlay.mjs';
+
+const TARGET_EXTENSION_MAP = Object.freeze({
+  '.gb': 'gb',
+  '.gbc': 'gbc',
+  '.gba': 'gba',
+});
+
+function inferTargetFromRomPath(romPath) {
+  return TARGET_EXTENSION_MAP[extname(String(romPath || '')).toLowerCase()] || null;
+}
+
+function resolveBuiltRomFromManifest({ projectRoot, target }) {
+  const manifestPath = resolve(projectRoot, 'build', target, 'retro-build-manifest.json');
+  if (!existsSync(manifestPath)) {
+    throw new RetroCompileError(
+      'retro_emulator_rom_not_found',
+      `No Retro build manifest was found for target "${target}". Run \`aura build --target ${target}\` first.`,
+      { manifestPath, target },
+    );
+  }
+  const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+  const romPath = typeof manifest?.romPath === 'string' && manifest.romPath.trim().length > 0
+    ? resolve(projectRoot, manifest.romPath)
+    : null;
+  if (!romPath || !existsSync(romPath)) {
+    throw new RetroCompileError(
+      'retro_emulator_rom_not_found',
+      `The Retro build manifest for target "${target}" does not point to a usable ROM artifact.`,
+      { manifestPath, romPath, target },
+    );
+  }
+  return {
+    target,
+    romPath,
+    manifestPath,
+  };
+}
+
+function resolveRetroRom({ projectRoot, target, romPath }) {
+  const explicitRomPath = String(romPath || '').trim();
+  if (explicitRomPath) {
+    const absoluteRomPath = resolve(projectRoot, explicitRomPath);
+    if (!existsSync(absoluteRomPath)) {
+      throw new RetroCompileError(
+        'retro_emulator_rom_not_found',
+        `Retro ROM path "${explicitRomPath}" does not exist.`,
+        { romPath: absoluteRomPath },
+      );
+    }
+    const inferredTarget = inferTargetFromRomPath(absoluteRomPath);
+    return {
+      target: target || inferredTarget,
+      romPath: absoluteRomPath,
+      manifestPath: null,
+    };
+  }
+  if (!target) {
+    throw new RetroCompileError(
+      'retro_emulator_rom_not_found',
+      'Missing retro target or explicit ROM path. Use `--target <gb|gbc|gba>` or pass `--rom <path>`.',
+    );
+  }
+  return resolveBuiltRomFromManifest({ projectRoot, target });
+}
+
+function formatCheckedCandidates(checked) {
+  return checked.map((entry) => entry.command).filter(Boolean).join(', ');
+}
+
+function spawnAndWait(child, { timeoutMs = null, allowTimeoutSuccess = false }) {
+  return new Promise((resolvePromise, rejectPromise) => {
+    let finished = false;
+    let timeoutId = null;
+    if (Number.isFinite(timeoutMs) && timeoutMs > 0) {
+      timeoutId = setTimeout(() => {
+        if (finished) {
+          return;
+        }
+        finished = true;
+        child.kill('SIGTERM');
+        resolvePromise({
+          status: 'timed_out',
+          code: null,
+          signal: 'SIGTERM',
+          timedOut: true,
+          ok: allowTimeoutSuccess,
+        });
+      }, timeoutMs);
+    }
+    child.once('error', (error) => {
+      if (finished) {
+        return;
+      }
+      finished = true;
+      if (timeoutId) clearTimeout(timeoutId);
+      rejectPromise(error);
+    });
+    child.once('exit', (code, signal) => {
+      if (finished) {
+        return;
+      }
+      finished = true;
+      if (timeoutId) clearTimeout(timeoutId);
+      resolvePromise({
+        status: code === 0 ? 'exited' : 'failed',
+        code,
+        signal,
+        timedOut: false,
+        ok: code === 0,
+      });
+    });
+  });
+}
+
+export async function runRetroEmulator({
+  projectRoot = process.cwd(),
+  target = null,
+  romPath = null,
+  emulator = null,
+  headless = false,
+  scale = null,
+  caseOverlay = false,
+} = {}) {
+  const resolvedRom = resolveRetroRom({ projectRoot, target, romPath });
+  const discovery = discoverRetroEmulator({
+    target: resolvedRom.target,
+    explicitEmulator: emulator,
+    smoke: false,
+  });
+
+  if (discovery.unsupportedProfile) {
+    throw new RetroCompileError(
+      'retro_emulator_target_unsupported',
+      `Emulator "${discovery.unsupportedProfile.id}" does not support target "${resolvedRom.target}".`,
+      { checked: discovery.checked, target: resolvedRom.target },
+    );
+  }
+  if (!discovery.emulator) {
+    throw new RetroCompileError(
+      'retro_emulator_not_found',
+      `No supported emulator was found for target "${resolvedRom.target}". Tried: ${formatCheckedCandidates(discovery.checked) || '<none>'}.`,
+      { checked: discovery.checked, target: resolvedRom.target },
+    );
+  }
+
+  const args = discovery.emulator.argsFor({
+    romPath: resolvedRom.romPath,
+    smoke: false,
+    headless,
+    scale,
+  });
+  const child = spawn(discovery.emulator.executablePath, args, {
+    cwd: projectRoot,
+    stdio: 'inherit',
+    env: process.env,
+  });
+
+  let overlayChild = null;
+  if (shouldUseRetroCaseOverlay({
+    caseEnabled: caseOverlay,
+    profileId: discovery.emulator.profile?.id || null,
+    headless,
+  })) {
+    overlayChild = launchRetroCaseOverlay({
+      emulatorPid: child.pid,
+      profileId: discovery.emulator.profile?.id || null,
+    });
+    if (!overlayChild) {
+      process.stderr.write('Aura Retro: could not attach the macOS case overlay. The emulator will keep running without it.\n');
+    }
+  }
+
+  const result = await spawnAndWait(child, { timeoutMs: null, allowTimeoutSuccess: false });
+  if (overlayChild && !overlayChild.killed) {
+    overlayChild.kill('SIGTERM');
+  }
+  if (!result.ok) {
+    throw new RetroCompileError(
+      'retro_emulator_launch_failed',
+      `Emulator "${basename(discovery.emulator.executablePath)}" exited unexpectedly while launching "${basename(resolvedRom.romPath)}".`,
+      { result, romPath: resolvedRom.romPath, executablePath: discovery.emulator.executablePath },
+    );
+  }
+  return {
+    ok: true,
+    status: 'passed',
+    target: resolvedRom.target,
+    romPath: resolvedRom.romPath,
+    emulatorId: discovery.emulator.profile?.id || 'custom',
+    executablePath: discovery.emulator.executablePath,
+    caseOverlay: Boolean(caseOverlay && overlayChild),
+  };
+}
+
+export async function smokeRetroEmulator({
+  projectRoot = process.cwd(),
+  target = null,
+  romPath = null,
+  emulator = null,
+  timeoutMs = 1500,
+} = {}) {
+  const resolvedRom = resolveRetroRom({ projectRoot, target, romPath });
+  const discovery = discoverRetroEmulator({
+    target: resolvedRom.target,
+    explicitEmulator: emulator,
+    smoke: true,
+  });
+
+  if (discovery.unsupportedProfile) {
+    throw new RetroCompileError(
+      'retro_emulator_target_unsupported',
+      `Emulator "${discovery.unsupportedProfile.id}" does not support target "${resolvedRom.target}".`,
+      { checked: discovery.checked, target: resolvedRom.target },
+    );
+  }
+  if (!discovery.emulator) {
+    return {
+      ok: true,
+      status: 'skipped',
+      reasonCode: 'retro_emulator_not_found',
+      target: resolvedRom.target,
+      romPath: resolvedRom.romPath,
+      checked: discovery.checked,
+    };
+  }
+
+  const args = discovery.emulator.argsFor({
+    romPath: resolvedRom.romPath,
+    smoke: true,
+    headless: true,
+    scale: null,
+  });
+
+  const child = spawn(discovery.emulator.executablePath, args, {
+    cwd: projectRoot,
+    stdio: 'ignore',
+    env: process.env,
+  });
+
+  let result;
+  try {
+    result = await spawnAndWait(child, {
+      timeoutMs,
+      allowTimeoutSuccess: true,
+    });
+  } catch (error) {
+    throw new RetroCompileError(
+      'retro_emulator_launch_failed',
+      `Failed to launch emulator "${basename(discovery.emulator.executablePath)}" for "${basename(resolvedRom.romPath)}".`,
+      {
+        target: resolvedRom.target,
+        romPath: resolvedRom.romPath,
+        executablePath: discovery.emulator.executablePath,
+        cause: error instanceof Error ? error.message : String(error),
+      },
+    );
+  }
+
+  if (!result.ok) {
+    throw new RetroCompileError(
+      'retro_emulator_launch_failed',
+      `Emulator "${basename(discovery.emulator.executablePath)}" failed while boot-checking "${basename(resolvedRom.romPath)}".`,
+      {
+        target: resolvedRom.target,
+        romPath: resolvedRom.romPath,
+        executablePath: discovery.emulator.executablePath,
+        result,
+      },
+    );
+  }
+
+  return {
+    ok: true,
+    status: 'passed',
+    reasonCode: result.timedOut ? 'retro_emulator_boot_smoke_passed' : 'retro_emulator_boot_smoke_exited_cleanly',
+    target: resolvedRom.target,
+    romPath: resolvedRom.romPath,
+    emulatorId: discovery.emulator.profile?.id || 'custom',
+    executablePath: discovery.emulator.executablePath,
+    timeoutMs,
+    checked: discovery.checked,
+  };
+}

package/src/retro/frontend/load-project.mjs

@@ -0,0 +1,98 @@
+import { dirname, isAbsolute, resolve } from 'node:path';
+import {
+  inspectProjectModuleGraph,
+  isBundleError,
+  BUNDLE_ERROR_CODES,
+} from '../../bundler.mjs';
+import { createRetroDiagnostic } from '../diagnostics/emit.mjs';
+import { getRetroTargetProfile } from '../shared/targets.mjs';
+
+function normalizePath(projectRoot, value) {
+  if (!value) return null;
+  return isAbsolute(value) ? value : resolve(projectRoot, value);
+}
+
+function mapBundleErrorToDiagnostic(error) {
+  const detailMap = {
+    [BUNDLE_ERROR_CODES.SYNTAX_ERROR]: 'retro_module_syntax_error',
+    [BUNDLE_ERROR_CODES.MODULE_NOT_FOUND]: 'retro_module_not_found',
+    [BUNDLE_ERROR_CODES.UNSUPPORTED_SPECIFIER]: 'retro_import_specifier_unsupported',
+    [BUNDLE_ERROR_CODES.PATH_ESCAPE]: 'retro_import_path_escape',
+    [BUNDLE_ERROR_CODES.DYNAMIC_IMPORT]: 'retro_dynamic_import_unsupported',
+    [BUNDLE_ERROR_CODES.CIRCULAR_DEP]: 'retro_circular_dependency_unsupported',
+  };
+  const reasonCode = detailMap[error.code] || 'retro_module_syntax_error';
+  return createRetroDiagnostic({
+    reasonCode,
+    filePath: error.details?.file || error.details?.importer || null,
+    span: {
+      line: error.details?.line || null,
+      column: error.details?.column || 1,
+      endLine: error.details?.line || null,
+      endColumn: error.details?.column || 1,
+    },
+    message: error.message,
+    source: 'retro-frontend',
+  });
+}
+
+export function loadRetroProjectGraph(options = {}) {
+  const projectRoot = resolve(options.projectRoot || process.cwd());
+  const targetProfile = getRetroTargetProfile(options.target || 'gbc');
+  const entryFile = normalizePath(projectRoot, options.entryFile || 'src/main.js');
+  const sourceRoots = Array.isArray(options.sourceRoots) && options.sourceRoots.length > 0
+    ? options.sourceRoots.map((value) => normalizePath(projectRoot, value))
+    : [resolve(projectRoot, 'src')];
+  const moduleRoot = normalizePath(projectRoot, options.moduleRoot || sourceRoots[0] || projectRoot);
+
+  try {
+    const graph = inspectProjectModuleGraph({
+      projectRoot,
+      entryFile,
+      moduleRoot,
+      allowedSourceRoots: sourceRoots,
+    });
+    return {
+      ok: true,
+      target: targetProfile.target,
+      targetProfile,
+      projectRoot,
+      entryFile,
+      moduleRoot,
+      sourceRoots,
+      graph,
+    };
+  } catch (error) {
+    if (isBundleError(error)) {
+      return {
+        ok: false,
+        target: targetProfile.target,
+        targetProfile,
+        projectRoot,
+        entryFile,
+        moduleRoot,
+        sourceRoots,
+        graph: null,
+        diagnostics: [mapBundleErrorToDiagnostic(error)],
+      };
+    }
+    throw error;
+  }
+}
+
+export function summarizeRetroGraph(frontend) {
+  const graph = frontend?.graph;
+  if (!graph) return [];
+  return graph.order.map((filePath) => {
+    const moduleMeta = graph.modules.get(filePath);
+    return {
+      id: moduleMeta.id,
+      filePath: moduleMeta.filePath,
+      imports: moduleMeta.imports.map((entry) => ({
+        specifier: entry.specifier,
+        resolved: entry.resolved,
+        line: entry.line,
+      })),
+    };
+  });
+}

package/src/retro/index.mjs

@@ -0,0 +1,30 @@
+export { buildRetroProject } from './build.mjs';
+export { compileRetroAssets } from './assets/compile.mjs';
+export { buildRetroIr } from './ir/build-ir.mjs';
+export { buildGameBoyRom, computeGlobalChecksum, computeHeaderChecksum } from './backend-gbc/rom.mjs';
+export { buildGameBoyAdvanceRom, computeGbaHeaderComplementCheck } from './backend-gba/rom.mjs';
+export {
+  RetroCompileError,
+  formatRetroCompileError,
+  formatRetroDiagnosticReport,
+} from './diagnostics/emit.mjs';
+export { loadRetroProjectGraph } from './frontend/load-project.mjs';
+export { explainRetroProject, checkRetroProject } from './validator/check-project.mjs';
+export {
+  RETRO_TARGET_PROFILES,
+  SUPPORTED_RETRO_BUILD_TARGETS,
+  getRetroTargetProfile,
+  isRetroBuildTarget,
+} from './shared/targets.mjs';
+export { createGbcRuntimeContract } from './runtime-gbc/contract.mjs';
+export { createGbaRuntimeContract } from './runtime-gba/contract.mjs';
+export { discoverRetroEmulator } from './emulator/discovery.mjs';
+export { runRetroEmulator, smokeRetroEmulator } from './emulator/runner.mjs';
+export {
+  runRetroCommand,
+  runRetroCheckCommand,
+  runRetroExplainCommand,
+  runRetroRunCommand,
+  runRetroSmokeCommand,
+  RetroCliArgumentError,
+} from './cli/commands.mjs';

package/src/retro/ir/build-ir.mjs

@@ -0,0 +1,108 @@
+import { readFileSync } from 'node:fs';
+import { loadRetroProjectGraph } from '../frontend/load-project.mjs';
+import { checkRetroProject } from '../validator/check-project.mjs';
+import { RetroCompileError } from '../diagnostics/emit.mjs';
+
+const RUNTIME_HANDLE_PATTERNS = Object.freeze([
+  ['input', /\baura\.input\./g],
+  ['sprite', /\baura\.sprite\./g],
+  ['tilemap', /\baura\.tilemap\./g],
+  ['text', /\baura\.text\./g],
+  ['audio', /\baura\.audio\./g],
+  ['save', /\baura\.save\./g],
+]);
+
+function scanLifecycle(code) {
+  return {
+    exportsState: /\bexport\s+const\s+state\b/.test(code),
+    exportsSetup: /\bexport\s+function\s+setup\s*\(/.test(code),
+    exportsUpdate: /\bexport\s+function\s+update\s*\(/.test(code),
+    exportsDraw: /\bexport\s+function\s+draw\s*\(/.test(code),
+  };
+}
+
+function scanRuntimeHandles(code) {
+  const handles = [];
+  for (const [name, pattern] of RUNTIME_HANDLE_PATTERNS) {
+    if (pattern.test(code)) {
+      handles.push(name);
+    }
+  }
+  return handles;
+}
+
+export function buildRetroIr(options = {}) {
+  const validation = checkRetroProject(options);
+  if (!validation.ok) {
+    throw new RetroCompileError(
+      'retro_build_blocked_by_diagnostics',
+      'Aura Retro IR build is blocked by compiler diagnostics.',
+      { diagnostics: validation.diagnostics, report: validation },
+    );
+  }
+
+  const frontend = loadRetroProjectGraph(options);
+  if (!frontend.ok) {
+    throw new RetroCompileError(
+      'retro_build_blocked_by_diagnostics',
+      'Aura Retro IR build could not load the project graph.',
+      { diagnostics: frontend.diagnostics || [] },
+    );
+  }
+
+  const lifecycle = {
+    setup: [],
+    update: [],
+    draw: [],
+  };
+  let stateOwner = null;
+  const modules = frontend.graph.order.map((filePath) => {
+    const moduleMeta = frontend.graph.modules.get(filePath);
+    const code = readFileSync(filePath, 'utf8');
+    const flags = scanLifecycle(code);
+    const runtimeHandles = scanRuntimeHandles(code);
+    if (flags.exportsState && !stateOwner) {
+      stateOwner = moduleMeta.id;
+    }
+    if (flags.exportsSetup) lifecycle.setup.push(moduleMeta.id);
+    if (flags.exportsUpdate) lifecycle.update.push(moduleMeta.id);
+    if (flags.exportsDraw) lifecycle.draw.push(moduleMeta.id);
+    return {
+      id: moduleMeta.id,
+      filePath: moduleMeta.filePath,
+      imports: moduleMeta.imports.map((entry) => ({
+        specifier: entry.specifier,
+        resolved: entry.resolved,
+        targetModuleId: frontend.graph.modules.get(entry.resolved)?.id || null,
+      })),
+      exports: {
+        state: flags.exportsState,
+        setup: flags.exportsSetup,
+        update: flags.exportsUpdate,
+        draw: flags.exportsDraw,
+      },
+      runtimeHandles,
+    };
+  });
+
+  return {
+    schemaVersion: 1,
+    target: frontend.target,
+    targetProfile: frontend.targetProfile,
+    entryFile: frontend.entryFile,
+    moduleCount: modules.length,
+    modules,
+    lifecycle,
+    state: {
+      ownerModuleId: stateOwner,
+      exportName: stateOwner ? 'state' : null,
+      representation: stateOwner ? 'plain-object-export' : 'none',
+    },
+    runtimeOwnership: {
+      setupOwners: lifecycle.setup,
+      updateOwners: lifecycle.update,
+      drawOwners: lifecycle.draw,
+      handles: [...new Set(modules.flatMap((entry) => entry.runtimeHandles))].sort(),
+    },
+  };
+}