@auraindustry/aurajs 0.0.6 → 0.1.0

package/src/session-native-launcher.mjs

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+
+import { spawn } from 'node:child_process';
+import process from 'node:process';
+
+function parseArgs(argv) {
+  const parsed = {
+    cwd: process.cwd(),
+    executable: null,
+    args: [],
+  };
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const token = argv[i];
+    if (token === '--cwd') {
+      parsed.cwd = argv[i + 1] || parsed.cwd;
+      i += 1;
+      continue;
+    }
+    if (token === '--executable') {
+      parsed.executable = argv[i + 1] || null;
+      i += 1;
+      continue;
+    }
+    if (token === '--') {
+      parsed.args = argv.slice(i + 1);
+      break;
+    }
+  }
+
+  if (!parsed.executable) {
+    throw new Error('session-native-launcher requires --executable');
+  }
+
+  return parsed;
+}
+
+async function main() {
+  const parsed = parseArgs(process.argv.slice(2));
+  const child = spawn(parsed.executable, parsed.args, {
+    cwd: parsed.cwd,
+    stdio: 'inherit',
+    env: process.env,
+  });
+
+  child.on('error', (error) => {
+    process.stderr.write(`${error.message}\n`);
+    process.exit(1);
+  });
+
+  const forwardSignal = (signal) => {
+    if (!child.killed && child.exitCode == null) {
+      try {
+        child.kill(signal);
+      } catch {}
+    }
+  };
+
+  process.on('SIGTERM', () => forwardSignal('SIGTERM'));
+  process.on('SIGINT', () => forwardSignal('SIGINT'));
+
+  child.on('exit', (code, signal) => {
+    if (signal) {
+      process.exit(1);
+      return;
+    }
+    process.exit(code ?? 0);
+  });
+}
+
+main().catch((error) => {
+  process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+  process.exit(1);
+});

package/src/session-protocol.mjs

@@ -0,0 +1,75 @@
+export const DEV_SESSION_REGISTRY_SCHEMA_VERSION = 'aurajs.dev-session-registry.v1';
+export const DEV_SESSION_REQUEST_SCHEMA_VERSION = 'aurajs.dev-session-request.v1';
+export const DEV_SESSION_RESPONSE_SCHEMA_VERSION = 'aurajs.dev-session-response.v1';
+export const DEV_SESSION_REPORT_SCHEMA_VERSION = 'aurajs.dev-session-report.v1';
+
+export const DEFAULT_SESSION_WIDTH = 1280;
+export const DEFAULT_SESSION_HEIGHT = 720;
+export const DEFAULT_SESSION_REQUEST_TIMEOUT_MS = 5000;
+export const DEFAULT_SESSION_START_TIMEOUT_MS = 15000;
+
+export function orderSessionRecord(record) {
+  const ordered = {};
+  const keyOrder = [
+    'sessionId',
+    'name',
+    'mode',
+    'origin',
+    'launchReasonCode',
+    'controllerPid',
+    'pid',
+    'projectRoot',
+    'entryFile',
+    'socketPath',
+    'logPath',
+    'createdAt',
+    'frameIndex',
+    'elapsedSeconds',
+    'requestCount',
+    'current',
+  ];
+
+  for (const key of keyOrder) {
+    if (Object.prototype.hasOwnProperty.call(record, key)) {
+      ordered[key] = record[key];
+    }
+  }
+
+  return ordered;
+}
+
+export function orderSessionRegistry(registry) {
+  const ordered = {
+    schemaVersion: DEV_SESSION_REGISTRY_SCHEMA_VERSION,
+    currentSessionId: registry.currentSessionId || null,
+    sessions: Array.isArray(registry.sessions)
+      ? registry.sessions.map((record) => orderSessionRecord(record))
+      : [],
+  };
+
+  return ordered;
+}
+
+export function orderSessionReport(report) {
+  const ordered = {};
+  const keyOrder = [
+    'schemaVersion',
+    'ok',
+    'reasonCode',
+    'sessionId',
+    'currentSessionId',
+    'closed',
+    'stale',
+    'detail',
+    'session',
+    'sessions',
+  ];
+
+  for (const key of keyOrder) {
+    if (Object.prototype.hasOwnProperty.call(report, key)) {
+      ordered[key] = report[key];
+    }
+  }
+
+  return ordered;
+}

package/src/session-runtime.mjs

@@ -0,0 +1,321 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import vm from 'node:vm';
+
+import { bundleProject } from './bundler.mjs';
+import {
+  HeadlessTestError,
+  createHeadlessAura,
+  createRuntimeContext,
+  executeSetup,
+  executeFrameSteps,
+} from './headless-test.mjs';
+import {
+  GAME_ACTION_RESULT_SCHEMA_VERSION,
+} from './game-action-runtime.mjs';
+
+function cloneInspectorSnapshot(value) {
+  if (value == null) {
+    return null;
+  }
+  try {
+    return JSON.parse(JSON.stringify(value));
+  } catch {
+    return null;
+  }
+}
+
+function toFiniteNumberOrNull(value) {
+  return Number.isFinite(value) ? Number(value) : null;
+}
+
+function createUnavailableActionResult(reasonCode, detail) {
+  const payload = {
+    schemaVersion: GAME_ACTION_RESULT_SCHEMA_VERSION,
+    ok: false,
+    reasonCode: typeof reasonCode === 'string' && reasonCode
+      ? reasonCode
+      : 'action_run_failed',
+  };
+
+  if (typeof detail === 'string' && detail.trim()) {
+    payload.detail = detail.trim();
+  }
+
+  return payload;
+}
+
+function createSessionTestState() {
+  return {
+    failures: [],
+    passes: 0,
+    drawCalls: 0,
+    audioCalls: 0,
+    logs: [],
+  };
+}
+
+export async function bootSessionRuntime(options = {}) {
+  const projectRoot = resolve(options.projectRoot || process.cwd());
+  const entryFile = resolve(projectRoot, options.file || 'src/main.js');
+  const width = options.width ?? 1280;
+  const height = options.height ?? 720;
+  const outFile = resolve(projectRoot, options.outFile || '.aura/session/runtime.bundle.js');
+
+  if (!existsSync(entryFile)) {
+    throw new HeadlessTestError(`Session entry file not found: ${entryFile}`);
+  }
+
+  const bundle = bundleProject({
+    projectRoot,
+    mode: 'test',
+    entryFile,
+    outFile,
+  });
+
+  const testState = createSessionTestState();
+  const aura = createHeadlessAura({ width, height, testState });
+  const context = vm.createContext(createRuntimeContext(aura, testState));
+
+  const source = readFileSync(bundle.outFile, 'utf8');
+  const script = new vm.Script(source, {
+    filename: bundle.outFile,
+    displayErrors: true,
+  });
+
+  try {
+    script.runInContext(context, { timeout: 5000 });
+    await executeSetup(aura);
+  } catch (error) {
+    throw new HeadlessTestError(`Session runtime boot failed: ${error.message}`, {
+      stack: error.stack,
+    });
+  }
+
+  return {
+    aura,
+    bundle,
+    entryFile,
+    width,
+    height,
+    frameIndex: 0,
+    elapsedSeconds: 0,
+    testState,
+  };
+}
+
+export async function advanceSessionFrames(runtime, frames = 0) {
+  const nextFrames = Number.isInteger(Number(frames)) && Number(frames) >= 0
+    ? Number(frames)
+    : 0;
+
+  if (nextFrames === 0) return;
+  await executeFrameSteps(runtime.aura, nextFrames);
+  runtime.frameIndex += nextFrames;
+  runtime.elapsedSeconds += nextFrames / 60;
+}
+
+export function exportSessionState(runtime, options = {}) {
+  const stateNs = runtime.aura.state && typeof runtime.aura.state === 'object'
+    ? runtime.aura.state
+    : null;
+  if (!stateNs || typeof stateNs.exportState !== 'function') {
+    return {
+      ok: false,
+      reasonCode: 'state_export_failed',
+      detail: 'aura.state.exportState hook is unavailable.',
+    };
+  }
+
+  try {
+    return stateNs.exportState({
+      mode: options.mode || 'headless',
+      seed: options.seed,
+      frameIndex: runtime.frameIndex,
+      elapsedSeconds: runtime.elapsedSeconds,
+      capturedAt: options.capturedAt ?? null,
+    });
+  } catch (error) {
+    return {
+      ok: false,
+      reasonCode: 'state_export_failed',
+      detail: error instanceof Error ? error.message : String(error),
+    };
+  }
+}
+
+export function applySessionState(runtime, payload) {
+  const stateNs = runtime.aura.state && typeof runtime.aura.state === 'object'
+    ? runtime.aura.state
+    : null;
+  if (!stateNs || typeof stateNs.apply !== 'function') {
+    return {
+      ok: false,
+      reasonCode: 'state_apply_failed',
+      detail: 'aura.state.apply hook is unavailable.',
+    };
+  }
+
+  try {
+    return stateNs.apply(payload);
+  } catch (error) {
+    return {
+      ok: false,
+      reasonCode: 'state_apply_failed',
+      detail: error instanceof Error ? error.message : String(error),
+    };
+  }
+}
+
+export function getSessionActionSchema(runtime) {
+  const actionNs = runtime.aura.action && typeof runtime.aura.action === 'object'
+    ? runtime.aura.action
+    : null;
+  if (!actionNs || typeof actionNs.getSchema !== 'function') {
+    return {
+      ok: false,
+      reasonCode: 'action_contract_unavailable',
+      detail: 'aura.action.getSchema hook is unavailable.',
+    };
+  }
+
+  try {
+    return actionNs.getSchema();
+  } catch (error) {
+    return {
+      ok: false,
+      reasonCode: 'invalid_action_contract',
+      detail: error instanceof Error ? error.message : String(error),
+    };
+  }
+}
+
+export async function runSessionAction(runtime, options = {}) {
+  const request = options.request;
+  const actionNs = runtime.aura.action && typeof runtime.aura.action === 'object'
+    ? runtime.aura.action
+    : null;
+
+  if (!request || typeof request !== 'object' || Array.isArray(request)) {
+    return {
+      actionResult: createUnavailableActionResult('invalid_action_request', 'request must be an object'),
+      stateResult: null,
+    };
+  }
+  if (!actionNs || typeof actionNs.run !== 'function') {
+    return {
+      actionResult: createUnavailableActionResult('action_contract_unavailable', 'aura.action.run hook is unavailable.'),
+      stateResult: null,
+    };
+  }
+
+  let actionResult;
+  try {
+    actionResult = await Promise.resolve(actionNs.run(request));
+  } catch (error) {
+    actionResult = createUnavailableActionResult(
+      'action_run_failed',
+      error instanceof Error ? error.message : String(error),
+    );
+  }
+
+  let stateResult = null;
+  const frames = Number.isInteger(Number(options.frames)) && Number(options.frames) >= 0
+    ? Number(options.frames)
+    : 0;
+  if (options.includeState === true || frames > 0) {
+    await advanceSessionFrames(runtime, frames);
+    stateResult = exportSessionState(runtime, {
+      mode: options.mode || 'headless',
+      capturedAt: options.capturedAt ?? null,
+    });
+  }
+
+  return {
+    actionResult,
+    stateResult,
+  };
+}
+
+export async function exportSessionInspect(runtime, options = {}) {
+  const debugNs = runtime.aura.debug && typeof runtime.aura.debug === 'object'
+    ? runtime.aura.debug
+    : null;
+
+  if (!debugNs || typeof debugNs.enableInspector !== 'function' || typeof debugNs.inspectorStats !== 'function') {
+    return {
+      enabled: true,
+      status: 'fail',
+      reasonCode: 'runtime_inspector_snapshot_hooks_unavailable',
+      sourceCaseId: null,
+      snapshot: null,
+      error: 'aura.debug.enableInspector()/inspectorStats() unavailable',
+    };
+  }
+
+  try {
+    const baseline = cloneInspectorSnapshot(debugNs.inspectorStats());
+    debugNs.enableInspector(true);
+    await advanceSessionFrames(runtime, options.frames ?? 0);
+    const active = cloneInspectorSnapshot(debugNs.inspectorStats());
+    debugNs.enableInspector(false);
+    const afterDisable = cloneInspectorSnapshot(debugNs.inspectorStats());
+
+    const snapshot = !active || active.enabled !== true
+      ? null
+      : {
+          status: 'pass',
+          reasonCode: 'runtime_inspector_snapshot_ok',
+          defaultDisabledLowOverhead: baseline?.enabled === false,
+          frame: {
+            frameCount: toFiniteNumberOrNull(active.frameCount),
+            fps: toFiniteNumberOrNull(active?.frame?.fps),
+            deltaSeconds: toFiniteNumberOrNull(active?.frame?.deltaSeconds),
+            elapsedSeconds: toFiniteNumberOrNull(active?.frame?.elapsedSeconds),
+          },
+          window: active?.window || null,
+          queues: active?.queues || null,
+          resetAfterDisable: {
+            enabled: afterDisable?.enabled === false,
+            frameCount: toFiniteNumberOrNull(afterDisable?.frameCount),
+            elapsedSeconds: toFiniteNumberOrNull(afterDisable?.frame?.elapsedSeconds),
+          },
+          phase2: active?.phase2 || null,
+          draw2dRuntime: active?.draw2dRuntime || null,
+          scene3dRuntime: active?.scene3dRuntime || null,
+          raw: {
+            baseline,
+            active,
+            afterDisable,
+          },
+        };
+
+    return snapshot
+      ? {
+          enabled: true,
+          status: 'pass',
+          reasonCode: 'runtime_inspector_snapshot_ok',
+          sourceCaseId: null,
+          snapshot,
+          error: null,
+        }
+      : {
+          enabled: true,
+          status: 'fail',
+          reasonCode: 'runtime_inspector_snapshot_disabled',
+          sourceCaseId: null,
+          snapshot: null,
+          error: 'Inspector did not report enabled stats after enableInspector(true).',
+        };
+  } catch (error) {
+    return {
+      enabled: true,
+      status: 'fail',
+      reasonCode: 'runtime_inspector_snapshot_collect_failed',
+      sourceCaseId: null,
+      snapshot: null,
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+}
+