@auraindustry/aurajs 0.0.7 → 0.1.0

package/src/retro/build.mjs

@@ -0,0 +1,278 @@
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { resolve, basename } from 'node:path';
+import { explainRetroProject } from './validator/check-project.mjs';
+import { RetroCompileError } from './diagnostics/emit.mjs';
+import { getRetroTargetProfile } from './shared/targets.mjs';
+import { relFile } from './shared/span.mjs';
+import { buildRetroIr } from './ir/build-ir.mjs';
+import { buildGameBoyRom } from './backend-gbc/rom.mjs';
+import {
+  buildGameBoyAdvanceRom,
+  buildPlayableGameBoyAdvancePayload,
+} from './backend-gba/rom.mjs';
+import { compileRetroAssets } from './assets/compile.mjs';
+
+function createPreviewSource({ targetProfile, identity, report }) {
+  const moduleList = report.modules.map((entry) => ` * - ${relFile(report.projectRoot, entry.filePath)}`).join('\n');
+  return [
+    '/*',
+    ` * Aura Retro preview source bundle`,
+    ` * Target: ${targetProfile.target} (${targetProfile.displayName})`,
+    ` * Game: ${identity.name} ${identity.version}`,
+    ' *',
+    ' * This preview lane validates the supported Aura Retro subset and emits',
+    ' * cartridge-oriented scaffold sources without changing the default desktop runtime.',
+    ' */',
+    '',
+    '#include <stdint.h>',
+    '',
+    `#define AURA_RETRO_TARGET_${targetProfile.target.toUpperCase()} 1`,
+    '',
+    'typedef struct AuraRetroState {',
+    '  uint32_t frame;',
+    '} AuraRetroState;',
+    '',
+    'static AuraRetroState state = {0};',
+    '',
+    'static void aura_setup(void) {',
+    '  state.frame = 0;',
+    '}',
+    '',
+    'static void aura_update(void) {',
+    '  state.frame += 1;',
+    '}',
+    '',
+    'static void aura_draw(void) {',
+    '  (void)state.frame;',
+    '}',
+    '',
+    'int main(void) {',
+    '  aura_setup();',
+    '  for (;;) {',
+    '    aura_update();',
+    '    aura_draw();',
+    '  }',
+    '  return 0;',
+    '}',
+    '',
+    '/* Source modules validated for this preview build:',
+    moduleList || ' * - <none>',
+    ' */',
+    '',
+  ].join('\n');
+}
+
+function createToolchainNotes({ targetProfile, report, gbaRuntime = null }) {
+  const outputNotes = targetProfile.family === 'gb' || targetProfile.family === 'gba'
+    ? [
+      'This build lane emits a cartridge ROM, analysis report, IR, asset manifest, and preview C source.',
+      'Use the ROM artifact for smoke checks and the preview source bundle to inspect compiler output.',
+    ]
+    : [
+      'This build lane currently emits validated preview sources, manifests, and analysis artifacts.',
+      'A final cartridge ROM toolchain is still a follow-up task for this target.',
+    ];
+  return [
+    `Aura Retro preview build for ${targetProfile.displayName}`,
+    '',
+    `Validated entry: ${relFile(report.projectRoot, report.entryFile)}`,
+    `Modules: ${report.moduleCount}`,
+    `Suggested toolchain: ${targetProfile.suggestedToolchain}`,
+    ...(targetProfile.family === 'gba'
+      ? [`Runtime mode: ${gbaRuntime?.mode || 'header-stub'}`]
+      : []),
+    '',
+    ...outputNotes,
+    '',
+  ].join('\n');
+}
+
+function buildRetroRom({
+  identity,
+  targetProfile,
+  ir,
+  generatedDir,
+  report,
+  assets,
+  logOutput,
+}) {
+  if (targetProfile.family === 'gb') {
+    return {
+      romBytes: buildGameBoyRom({ identity, targetProfile, ir }),
+      runtimeMode: 'header-stub',
+      runtimeArtifacts: null,
+    };
+  }
+  if (targetProfile.family === 'gba') {
+    const gbaRuntime = buildPlayableGameBoyAdvancePayload({
+      identity,
+      generatedDir,
+      entryFile: report.entryFile,
+      ir,
+      assets: assets.compiled,
+      logOutput,
+    });
+    return {
+      romBytes: buildGameBoyAdvanceRom({
+        identity,
+        targetProfile,
+        ir,
+        payload: gbaRuntime.ok ? gbaRuntime.payload : null,
+      }),
+      runtimeMode: gbaRuntime.mode,
+      runtimeArtifacts: gbaRuntime.ok
+        ? {
+          runtimeSourcePath: gbaRuntime.runtimeSourcePath,
+          linkerScriptPath: gbaRuntime.linkerScriptPath,
+          objectPath: gbaRuntime.objectPath,
+          elfPath: gbaRuntime.elfPath,
+          binaryPath: gbaRuntime.binaryPath,
+        }
+        : null,
+    };
+  }
+  return {
+    romBytes: null,
+    runtimeMode: 'preview-only',
+    runtimeArtifacts: null,
+  };
+}
+
+export function buildRetroProject({
+  projectRoot,
+  config,
+  entryFile,
+  target,
+  identity,
+  logOutput = true,
+}) {
+  const targetProfile = getRetroTargetProfile(target);
+  const report = explainRetroProject({
+    projectRoot,
+    entryFile,
+    target,
+  });
+  const ir = report.ok
+    ? buildRetroIr({
+      projectRoot,
+      entryFile,
+      target,
+    })
+    : null;
+
+  if (!report.ok) {
+    throw new RetroCompileError(
+      'retro_build_blocked_by_diagnostics',
+      `Aura Retro build blocked for target "${target}".`,
+      { diagnostics: report.diagnostics, report },
+    );
+  }
+
+  const targetOutRoot = resolve(projectRoot, config.build.outDir, target);
+  const generatedDir = resolve(targetOutRoot, 'generated');
+  mkdirSync(generatedDir, { recursive: true });
+  const assets = compileRetroAssets({
+    projectRoot,
+    target,
+    emitCompiled: true,
+    outRoot: targetOutRoot,
+  });
+
+  const manifestPath = resolve(targetOutRoot, 'retro-build-manifest.json');
+  const analysisPath = resolve(targetOutRoot, 'retro-analysis.json');
+  const irPath = resolve(targetOutRoot, 'retro-ir.json');
+  const previewSourcePath = resolve(generatedDir, 'cartridge-preview.c');
+  const toolchainNotesPath = resolve(targetOutRoot, 'toolchain-notes.txt');
+  const retroRom = buildRetroRom({
+    identity,
+    targetProfile,
+    ir,
+    generatedDir,
+    report,
+    assets,
+    logOutput,
+  });
+  const romPath = retroRom.romBytes
+    ? resolve(targetOutRoot, `${identity.executableBaseName}${targetProfile.outputExtension}`)
+    : null;
+
+  const manifest = {
+    schemaVersion: 1,
+    artifactKind: romPath ? 'retro-rom-build' : 'retro-preview-build',
+    reasonCode: romPath ? 'retro_build_rom_ready' : 'retro_build_preview_ready',
+    target,
+    displayName: targetProfile.displayName,
+    architecture: targetProfile.architecture,
+    colorMode: targetProfile.colorMode,
+    projectRoot,
+    entryFile: report.entryFile,
+    moduleCount: report.moduleCount,
+    assetsPath: assets.outputPath,
+    assetSummary: assets.summary,
+    irPath,
+    romPath,
+    runtimeMode: retroRom.runtimeMode,
+    runtimeArtifacts: retroRom.runtimeArtifacts,
+    previewSourcePath,
+    analysisPath,
+    toolchainNotesPath,
+  };
+
+  writeFileSync(analysisPath, `${JSON.stringify(report, null, 2)}\n`, 'utf8');
+  writeFileSync(irPath, `${JSON.stringify(ir, null, 2)}\n`, 'utf8');
+  if (romPath) {
+    writeFileSync(romPath, retroRom.romBytes);
+  }
+  writeFileSync(previewSourcePath, createPreviewSource({ targetProfile, identity, report }), 'utf8');
+  writeFileSync(toolchainNotesPath, createToolchainNotes({
+    targetProfile,
+    report,
+    gbaRuntime: {
+      mode: retroRom.runtimeMode,
+    },
+  }), 'utf8');
+  writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, 'utf8');
+
+  if (logOutput) {
+    console.log('\n  aura build: complete.');
+    console.log(`  Game: ${identity.name}`);
+    console.log(`  Version: ${identity.version}`);
+    console.log(`  Output target: ${target}`);
+    console.log(`  Retro profile: ${targetProfile.displayName}`);
+    console.log(`  Modules: ${report.moduleCount}`);
+    console.log(`  Assets: ${assets.summary ? `palettes=${assets.summary.paletteCount} tiles=${assets.summary.tileCount} sprites=${assets.summary.spriteCount} fonts=${assets.summary.fontCount}` : 'none'}`);
+    if (romPath) {
+      console.log(`  ROM artifact: ${basename(romPath)}`);
+    } else {
+      console.log('  ROM artifact: not emitted for this target yet');
+    }
+    if (targetProfile.family === 'gba') {
+      console.log(`  GBA runtime: ${retroRom.runtimeMode}`);
+    }
+    console.log(`  Artifact mode: ${romPath ? 'retro ROM + preview source bundle' : 'retro preview source bundle'}`);
+    console.log('');
+  }
+
+  return {
+    projectRoot,
+    config,
+    requestedTarget: target,
+    platformTarget: null,
+    effectiveTarget: target,
+    targetKind: 'retro',
+    targetOutRoot,
+    executablePath: null,
+    launchExecutablePath: null,
+    bundlePath: null,
+    buildManifestPath: manifestPath,
+    assetsManifestPath: null,
+    assetMode: 'retro-assets',
+    identity,
+    retroAnalysisPath: analysisPath,
+    retroAssetsPath: assets.outputPath,
+    retroIrPath: irPath,
+    romPath,
+    previewSourcePath,
+    toolchainNotesPath,
+  };
+}

package/src/retro/cli/commands.mjs

@@ -0,0 +1,292 @@
+import { explainRetroProject } from '../validator/check-project.mjs';
+import { formatRetroDiagnosticReport } from '../diagnostics/emit.mjs';
+import { isRetroBuildTarget } from '../shared/targets.mjs';
+import { runRetroEmulator, smokeRetroEmulator } from '../emulator/runner.mjs';
+
+class RetroCliArgumentError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'RetroCliArgumentError';
+  }
+}
+
+function parseRetroArgs(args) {
+  const parsed = {
+    entryFile: null,
+    json: false,
+    compact: false,
+    target: 'gbc',
+  };
+
+  let positionalSeen = false;
+  for (let index = 0; index < args.length; index += 1) {
+    const token = String(args[index] || '');
+    if (token === '--json') {
+      parsed.json = true;
+      continue;
+    }
+    if (token === '--compact') {
+      parsed.compact = true;
+      continue;
+    }
+    if (token === '--entry') {
+      if ((index + 1) >= args.length) {
+        throw new RetroCliArgumentError('--entry requires a file path.');
+      }
+      parsed.entryFile = String(args[index + 1] || '');
+      index += 1;
+      continue;
+    }
+    if (token.startsWith('--entry=')) {
+      parsed.entryFile = token.slice('--entry='.length);
+      continue;
+    }
+    if (token === '--target') {
+      if ((index + 1) >= args.length) {
+        throw new RetroCliArgumentError('--target requires a value.');
+      }
+      parsed.target = String(args[index + 1] || '').trim().toLowerCase();
+      index += 1;
+      continue;
+    }
+    if (token.startsWith('--target=')) {
+      parsed.target = token.slice('--target='.length).trim().toLowerCase();
+      continue;
+    }
+    if (token.startsWith('--')) {
+      throw new RetroCliArgumentError(`Unknown retro option: ${token}`);
+    }
+    if (positionalSeen) {
+      throw new RetroCliArgumentError(`Unexpected argument: ${token}`);
+    }
+    parsed.entryFile = token;
+    positionalSeen = true;
+  }
+
+  if (!isRetroBuildTarget(parsed.target)) {
+    throw new RetroCliArgumentError(`Unsupported retro target "${parsed.target}". Supported values: gb, gbc, gba.`);
+  }
+
+  return parsed;
+}
+
+function parseRetroLaunchArgs(args, { allowJson = false, smoke = false } = {}) {
+  const parsed = {
+    target: null,
+    romPath: null,
+    emulator: null,
+    scale: null,
+    caseOverlay: false,
+    timeoutMs: 1500,
+    json: false,
+    compact: false,
+    headless: false,
+  };
+
+  for (let index = 0; index < args.length; index += 1) {
+    const token = String(args[index] || '');
+    if (token === '--target') {
+      if ((index + 1) >= args.length) {
+        throw new RetroCliArgumentError('--target requires a value.');
+      }
+      parsed.target = String(args[index + 1] || '').trim().toLowerCase();
+      index += 1;
+      continue;
+    }
+    if (token.startsWith('--target=')) {
+      parsed.target = token.slice('--target='.length).trim().toLowerCase();
+      continue;
+    }
+    if (token === '--rom') {
+      if ((index + 1) >= args.length) {
+        throw new RetroCliArgumentError('--rom requires a file path.');
+      }
+      parsed.romPath = String(args[index + 1] || '');
+      index += 1;
+      continue;
+    }
+    if (token.startsWith('--rom=')) {
+      parsed.romPath = token.slice('--rom='.length);
+      continue;
+    }
+    if (token === '--emulator') {
+      if ((index + 1) >= args.length) {
+        throw new RetroCliArgumentError('--emulator requires a path or command name.');
+      }
+      parsed.emulator = String(args[index + 1] || '');
+      index += 1;
+      continue;
+    }
+    if (token.startsWith('--emulator=')) {
+      parsed.emulator = token.slice('--emulator='.length);
+      continue;
+    }
+    if (token === '--scale') {
+      if ((index + 1) >= args.length) {
+        throw new RetroCliArgumentError('--scale requires a numeric value.');
+      }
+      parsed.scale = Number(args[index + 1]);
+      index += 1;
+      continue;
+    }
+    if (token.startsWith('--scale=')) {
+      parsed.scale = Number(token.slice('--scale='.length));
+      continue;
+    }
+    if (token === '--case') {
+      if (smoke) {
+        throw new RetroCliArgumentError('--case is only supported for `aura retro run`.');
+      }
+      parsed.caseOverlay = true;
+      continue;
+    }
+    if (token === '--timeout-ms') {
+      if ((index + 1) >= args.length) {
+        throw new RetroCliArgumentError('--timeout-ms requires a numeric value.');
+      }
+      parsed.timeoutMs = Number(args[index + 1]);
+      index += 1;
+      continue;
+    }
+    if (token.startsWith('--timeout-ms=')) {
+      parsed.timeoutMs = Number(token.slice('--timeout-ms='.length));
+      continue;
+    }
+    if (token === '--headless') {
+      parsed.headless = true;
+      continue;
+    }
+    if (token === '--json') {
+      if (!allowJson) {
+        throw new RetroCliArgumentError('--json is only supported for `aura retro smoke`.');
+      }
+      parsed.json = true;
+      continue;
+    }
+    if (token === '--compact') {
+      if (!allowJson) {
+        throw new RetroCliArgumentError('--compact is only supported for `aura retro smoke --json`.');
+      }
+      parsed.compact = true;
+      continue;
+    }
+    if (token.startsWith('--')) {
+      throw new RetroCliArgumentError(`Unknown retro option: ${token}`);
+    }
+    throw new RetroCliArgumentError(`Unexpected argument: ${token}`);
+  }
+
+  if (parsed.target && !isRetroBuildTarget(parsed.target)) {
+    throw new RetroCliArgumentError(`Unsupported retro target "${parsed.target}". Supported values: gb, gbc, gba.`);
+  }
+  if (parsed.scale != null && (!Number.isFinite(parsed.scale) || parsed.scale <= 0)) {
+    throw new RetroCliArgumentError('--scale must be a positive number.');
+  }
+  if (!parsed.target && !parsed.romPath) {
+    parsed.target = 'gbc';
+  }
+  if (parsed.caseOverlay && parsed.scale == null) {
+    parsed.scale = 4;
+  }
+  if (smoke && (!Number.isFinite(parsed.timeoutMs) || parsed.timeoutMs <= 0)) {
+    throw new RetroCliArgumentError('--timeout-ms must be a positive number.');
+  }
+  return parsed;
+}
+
+function writeRetroReport(report, parsed) {
+  if (parsed.json) {
+    const payload = parsed.compact ? JSON.stringify(report) : JSON.stringify(report, null, 2);
+    process.stdout.write(`${payload}\n`);
+    return;
+  }
+  process.stdout.write(`${formatRetroDiagnosticReport(report, report.projectRoot)}\n`);
+}
+
+export function runRetroCheckCommand(args = []) {
+  const parsed = parseRetroArgs(args);
+  const report = explainRetroProject({
+    entryFile: parsed.entryFile || 'src/main.js',
+    target: parsed.target,
+  });
+  writeRetroReport(report, parsed);
+  if (!report.ok) {
+    process.exitCode = 7;
+  }
+}
+
+export function runRetroExplainCommand(args = []) {
+  const parsed = parseRetroArgs(args);
+  const report = explainRetroProject({
+    entryFile: parsed.entryFile || 'src/main.js',
+    target: parsed.target,
+  });
+  writeRetroReport(report, parsed);
+  if (!report.ok) {
+    process.exitCode = 7;
+  }
+}
+
+export async function runRetroRunCommand(args = []) {
+  const parsed = parseRetroLaunchArgs(args, { allowJson: false, smoke: false });
+  await runRetroEmulator({
+    projectRoot: process.cwd(),
+    target: parsed.target,
+    romPath: parsed.romPath,
+    emulator: parsed.emulator,
+    scale: parsed.scale,
+    caseOverlay: parsed.caseOverlay,
+    headless: parsed.headless,
+  });
+}
+
+export async function runRetroSmokeCommand(args = []) {
+  const parsed = parseRetroLaunchArgs(args, { allowJson: true, smoke: true });
+  const result = await smokeRetroEmulator({
+    projectRoot: process.cwd(),
+    target: parsed.target,
+    romPath: parsed.romPath,
+    emulator: parsed.emulator,
+    timeoutMs: parsed.timeoutMs,
+  });
+  if (parsed.json) {
+    const payload = parsed.compact ? JSON.stringify(result) : JSON.stringify(result, null, 2);
+    process.stdout.write(`${payload}\n`);
+    return;
+  }
+  if (result.status === 'skipped') {
+    process.stdout.write(
+      `Aura Retro smoke skipped (${result.target}): no supported emulator found. Tried: ${result.checked.map((entry) => entry.command).join(', ') || '<none>'}.\n`,
+    );
+    return;
+  }
+  process.stdout.write(
+    `Aura Retro smoke passed (${result.target}) using ${result.emulatorId} on ${result.romPath}.\n`,
+  );
+}
+
+export async function runRetroCommand(args = []) {
+  const subcommand = String(args[0] || '').trim();
+  if (!subcommand) {
+    throw new RetroCliArgumentError('Missing retro subcommand. Usage: aura retro <check|explain|run|smoke> [options]');
+  }
+  if (subcommand === 'check') {
+    runRetroCheckCommand(args.slice(1));
+    return;
+  }
+  if (subcommand === 'explain') {
+    runRetroExplainCommand(args.slice(1));
+    return;
+  }
+  if (subcommand === 'run') {
+    await runRetroRunCommand(args.slice(1));
+    return;
+  }
+  if (subcommand === 'smoke') {
+    await runRetroSmokeCommand(args.slice(1));
+    return;
+  }
+  throw new RetroCliArgumentError(`Unknown retro subcommand "${subcommand}". Supported subcommands: check, explain, run, smoke.`);
+}
+
+export { RetroCliArgumentError };

package/src/retro/cli/templates.mjs

@@ -0,0 +1,84 @@
+import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { basename, dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const TEMPLATE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '../../../templates/retro');
+
+const TEMPLATE_SUMMARIES = Object.freeze({
+  'topdown-adventure': 'Directional movement, room-scale exploration, HUD text, and a single hero sprite.',
+  'puzzle-grid': 'Grid cursor puzzle shell with deterministic input and one-screen board state.',
+  'tactics-grid': 'Turn-based tactics starter with unit selection, action points, and HUD info.',
+  platformer: 'Simple side-view platformer loop with jump physics and tile-ground assumptions.',
+});
+
+function projectSlugFromDestination(destination) {
+  return basename(resolve(destination))
+    .toLowerCase()
+    .replace(/[^a-z0-9._-]+/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/^-+|-+$/g, '') || 'retro-project';
+}
+
+function replaceTokens(text, tokens) {
+  let output = String(text);
+  for (const [token, value] of Object.entries(tokens)) {
+    output = output.replaceAll(token, value);
+  }
+  return output;
+}
+
+function copyTemplateTree(sourceRoot, destinationRoot, tokens) {
+  mkdirSync(destinationRoot, { recursive: true });
+  for (const entry of readdirSync(sourceRoot)) {
+    const sourcePath = resolve(sourceRoot, entry);
+    const destPath = resolve(destinationRoot, entry);
+    const stats = statSync(sourcePath);
+    if (stats.isDirectory()) {
+      copyTemplateTree(sourcePath, destPath, tokens);
+      continue;
+    }
+    const ext = entry.split('.').pop() || '';
+    if (['js', 'json', 'md', 'txt'].includes(ext)) {
+      writeFileSync(destPath, replaceTokens(readFileSync(sourcePath, 'utf8'), tokens), 'utf8');
+      continue;
+    }
+    cpSync(sourcePath, destPath);
+  }
+}
+
+export function listRetroTemplates() {
+  return readdirSync(TEMPLATE_ROOT)
+    .filter((entry) => statSync(resolve(TEMPLATE_ROOT, entry)).isDirectory())
+    .sort()
+    .map((id) => ({
+      id,
+      summary: TEMPLATE_SUMMARIES[id] || 'Aura Retro starter template.',
+    }));
+}
+
+export function initRetroTemplate({ destination, template, force = false }) {
+  const templateRoot = resolve(TEMPLATE_ROOT, template);
+  if (!existsSync(templateRoot)) {
+    throw new Error(`Unknown retro template "${template}".`);
+  }
+  const destinationRoot = resolve(destination);
+  if (existsSync(destinationRoot) && !force) {
+    throw new Error(`Destination already exists: ${destinationRoot}`);
+  }
+  const slug = projectSlugFromDestination(destinationRoot);
+  const prettyName = slug
+    .split(/[-_.]+/)
+    .filter(Boolean)
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join(' ') || 'Retro Project';
+  copyTemplateTree(templateRoot, destinationRoot, {
+    '__AURA_RETRO_PROJECT_SLUG__': slug,
+    '__AURA_RETRO_PROJECT_NAME__': prettyName,
+  });
+  return {
+    destinationRoot,
+    template,
+    slug,
+    name: prettyName,
+  };
+}