@auraindustry/aurajs 0.0.1

package/src/host-binary.mjs

@@ -0,0 +1,423 @@
+import { createRequire } from 'node:module';
+import { basename, dirname, join, resolve } from 'node:path';
+import {
+  accessSync,
+  existsSync,
+  readFileSync,
+  mkdirSync,
+  copyFileSync,
+  statSync,
+  writeFileSync,
+  unlinkSync,
+  constants as fsConstants,
+} from 'node:fs';
+import { createHash } from 'node:crypto';
+import { homedir } from 'node:os';
+
+const requireFromHere = createRequire(import.meta.url);
+
+const HOST_PACKAGE_SPECS = Object.freeze([
+  Object.freeze({
+    platform: 'darwin',
+    arch: 'arm64',
+    target: 'darwin-arm64',
+    packageName: '@aurajs/darwin-arm64',
+    binaryRelativePath: 'bin/aurajs-host',
+  }),
+  Object.freeze({
+    platform: 'darwin',
+    arch: 'x64',
+    target: 'darwin-x64',
+    packageName: '@aurajs/darwin-x64',
+    binaryRelativePath: 'bin/aurajs-host',
+  }),
+  Object.freeze({
+    platform: 'linux',
+    arch: 'x64',
+    target: 'linux-x64',
+    packageName: '@aurajs/linux-x64',
+    binaryRelativePath: 'bin/aurajs-host',
+  }),
+  Object.freeze({
+    platform: 'win32',
+    arch: 'x64',
+    target: 'win32-x64',
+    packageName: '@aurajs/win32-x64',
+    binaryRelativePath: 'bin/aurajs-host.exe',
+  }),
+]);
+
+function readJsonFile(path) {
+  return JSON.parse(readFileSync(path, 'utf8'));
+}
+
+function findPackageRootFromResolvedFile(resolvedFile, packageName, readPackageJson) {
+  let cursor = dirname(resolvedFile);
+  while (true) {
+    const packageJsonPath = join(cursor, 'package.json');
+    try {
+      const packageJson = readPackageJson(packageJsonPath);
+      if (packageJson?.name === packageName) {
+        return cursor;
+      }
+    } catch {}
+
+    const parent = dirname(cursor);
+    if (parent === cursor) {
+      return null;
+    }
+    cursor = parent;
+  }
+}
+
+function supportedTargetsLabel() {
+  return HOST_PACKAGE_SPECS.map((spec) => `${spec.platform}-${spec.arch}`).join(', ');
+}
+
+function hashFile(path) {
+  const hash = createHash('sha256');
+  hash.update(readFileSync(path));
+  return hash.digest('hex');
+}
+
+function defaultCacheRoot() {
+  return process.env.AURAJS_HOST_CACHE_DIR || join(homedir(), '.cache', 'aurajs', 'host-binaries');
+}
+
+function resolveOverrideHostBinaryPath({
+  platform = process.platform,
+  arch = process.arch,
+  fileExists = existsSync,
+} = {}) {
+  const overridePath = process.env.AURAJS_HOST_BINARY_PATH;
+  if (!overridePath) return null;
+
+  const resolvedOverridePath = resolve(overridePath);
+  if (!fileExists(resolvedOverridePath)) {
+    throw new HostBinaryResolutionError(
+      `AURAJS_HOST_BINARY_PATH is set, but file is missing: "${resolvedOverridePath}".`,
+      {
+        code: 'AURA_HOST_BINARY_OVERRIDE_MISSING',
+        platform,
+        arch,
+      },
+    );
+  }
+
+  const spec = getHostPackageSpec({ platform, arch });
+  return {
+    ...spec,
+    packageRoot: dirname(resolvedOverridePath),
+    binaryPath: resolvedOverridePath,
+    override: true,
+  };
+}
+
+function safeUnlink(path) {
+  try {
+    unlinkSync(path);
+  } catch {}
+}
+
+function resolveCacheInfo(spec, binaryPath, packageRoot, packageVersion, cacheRoot) {
+  const binaryStats = statSync(binaryPath);
+  const cacheDir = resolve(cacheRoot, spec.target, packageVersion || 'unknown');
+  const cachedBinaryPath = resolve(cacheDir, basename(binaryPath));
+  const manifestPath = resolve(cacheDir, 'manifest.json');
+  return {
+    cacheDir,
+    cachedBinaryPath,
+    manifestPath,
+    sourceStat: {
+      size: binaryStats.size,
+      mtimeMs: binaryStats.mtimeMs,
+      mode: binaryStats.mode,
+    },
+    sourceBinaryPath: binaryPath,
+    packageRoot,
+  };
+}
+
+export class HostBinaryResolutionError extends Error {
+  constructor(message, { code = 'AURA_HOST_BINARY_ERROR', platform, arch, packageName, cause } = {}) {
+    super(message, cause ? { cause } : undefined);
+    this.name = 'HostBinaryResolutionError';
+    this.code = code;
+    this.platform = platform;
+    this.arch = arch;
+    this.packageName = packageName;
+  }
+}
+
+export function getHostPackageSpec({ platform = process.platform, arch = process.arch } = {}) {
+  const spec = HOST_PACKAGE_SPECS.find((entry) => entry.platform === platform && entry.arch === arch);
+  if (!spec) {
+    throw new HostBinaryResolutionError(
+      `Unsupported host target "${platform}-${arch}". Supported targets: ${supportedTargetsLabel()}. Build on a supported platform or use CI cross-platform artifacts.`,
+      { code: 'AURA_HOST_UNSUPPORTED_TARGET', platform, arch },
+    );
+  }
+  return spec;
+}
+
+export function resolveHostBinaryPath({
+  platform = process.platform,
+  arch = process.arch,
+  requireResolve = (specifier) => requireFromHere.resolve(specifier),
+  fileExists = existsSync,
+  readPackageJson = readJsonFile,
+  resolvePackageRoot,
+} = {}) {
+  const override = resolveOverrideHostBinaryPath({ platform, arch, fileExists });
+  if (override) {
+    return override;
+  }
+
+  const spec = getHostPackageSpec({ platform, arch });
+  const packageRoot = resolvePackageRoot
+    ? resolvePackageRoot(spec.packageName)
+    : findInstalledPackageRoot(spec.packageName, { requireResolve, readPackageJson });
+
+  const binaryPath = resolve(packageRoot, spec.binaryRelativePath);
+  if (!fileExists(binaryPath)) {
+    throw new HostBinaryResolutionError(
+      `Host package "${spec.packageName}" is installed, but binary is missing at "${binaryPath}". Reinstall dependencies to restore platform binaries.`,
+      {
+        code: 'AURA_HOST_BINARY_MISSING',
+        platform,
+        arch,
+        packageName: spec.packageName,
+      },
+    );
+  }
+
+  return {
+    ...spec,
+    packageRoot,
+    binaryPath,
+  };
+}
+
+export function resolveAndCacheHostBinary({
+  platform = process.platform,
+  arch = process.arch,
+  cacheRoot = defaultCacheRoot(),
+  packageJsonVersion,
+  resolvePackageRoot,
+} = {}) {
+  const resolved = resolveHostBinaryPath({ platform, arch, resolvePackageRoot });
+
+  if (resolved.override) {
+    return {
+      ...resolved,
+      cacheDir: dirname(resolved.binaryPath),
+      cachedBinaryPath: resolved.binaryPath,
+      manifestPath: null,
+      cacheStatus: 'override',
+      diagnostics: ['Using AURAJS_HOST_BINARY_PATH override; cache step skipped.'],
+    };
+  }
+
+  let packageVersion = packageJsonVersion;
+  try {
+    const packageJson = readJsonFile(resolve(resolved.packageRoot, 'package.json'));
+    packageVersion = packageVersion || packageJson.version;
+  } catch {}
+
+  const cache = resolveCacheInfo(
+    resolved,
+    resolved.binaryPath,
+    resolved.packageRoot,
+    packageVersion,
+    cacheRoot,
+  );
+
+  mkdirSync(cache.cacheDir, { recursive: true });
+
+  const sourceHash = hashFile(cache.sourceBinaryPath);
+  const manifest = {
+    packageName: resolved.packageName,
+    target: resolved.target,
+    sourceBinaryPath: cache.sourceBinaryPath,
+    packageRoot: cache.packageRoot,
+    size: cache.sourceStat.size,
+    mtimeMs: cache.sourceStat.mtimeMs,
+    mode: cache.sourceStat.mode,
+    sha256: sourceHash,
+  };
+
+  let cacheHit = false;
+  if (existsSync(cache.cachedBinaryPath) && existsSync(cache.manifestPath)) {
+    try {
+      const prior = readJsonFile(cache.manifestPath);
+      const cachedStats = statSync(cache.cachedBinaryPath);
+      const cachedHash = hashFile(cache.cachedBinaryPath);
+      cacheHit = (
+        prior?.sha256 === sourceHash
+        && prior?.size === cache.sourceStat.size
+        && cachedStats.size === cache.sourceStat.size
+        && cachedHash === sourceHash
+      );
+    } catch {
+      cacheHit = false;
+    }
+  }
+
+  if (!cacheHit) {
+    safeUnlink(cache.cachedBinaryPath);
+    copyFileSync(cache.sourceBinaryPath, cache.cachedBinaryPath);
+    writeFileSync(cache.manifestPath, JSON.stringify(manifest, null, 2));
+  }
+
+  return {
+    ...resolved,
+    cacheDir: cache.cacheDir,
+    cachedBinaryPath: cache.cachedBinaryPath,
+    manifestPath: cache.manifestPath,
+    cacheStatus: cacheHit ? 'hit' : 'refreshed',
+    binaryPath: cache.cachedBinaryPath,
+    diagnostics: cacheHit
+      ? []
+      : ['Host binary cache was missing/stale/corrupt and has been refreshed from optionalDependencies.'],
+  };
+}
+
+function findInstalledPackageRoot(packageName, { requireResolve, readPackageJson }) {
+  try {
+    const packageJsonPath = requireResolve(`${packageName}/package.json`);
+    return dirname(packageJsonPath);
+  } catch {
+    // Fall through to entrypoint search.
+  }
+
+  let resolvedEntrypoint;
+  try {
+    resolvedEntrypoint = requireResolve(packageName);
+  } catch (cause) {
+    throw new HostBinaryResolutionError(
+      `Missing host package "${packageName}". Run "npm install" to install optional platform binaries.`,
+      { code: 'AURA_HOST_PACKAGE_MISSING', packageName, cause },
+    );
+  }
+
+  const packageRoot = findPackageRootFromResolvedFile(resolvedEntrypoint, packageName, readPackageJson);
+  if (!packageRoot) {
+    throw new HostBinaryResolutionError(
+      `Could not determine package root for "${packageName}" from "${resolvedEntrypoint}".`,
+      { code: 'AURA_HOST_PACKAGE_INVALID', packageName },
+    );
+  }
+
+  return packageRoot;
+}
+
+
+function resolveLocalHostBinaryCandidates(searchRoot, binaryName) {
+  return [
+    resolve(searchRoot, 'src', 'rust-host', 'target', 'debug', binaryName),
+    resolve(searchRoot, 'src', 'rust-host', 'target', 'release', binaryName),
+  ];
+}
+
+function canExecuteFile(path) {
+  try {
+    accessSync(path, fsConstants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function findRepoRootWithRustHost(startDir) {
+  let cursor = resolve(startDir || process.cwd());
+  while (true) {
+    const cargoToml = resolve(cursor, 'src', 'rust-host', 'Cargo.toml');
+    if (existsSync(cargoToml)) {
+      return cursor;
+    }
+    const parent = dirname(cursor);
+    if (parent === cursor) {
+      return null;
+    }
+    cursor = parent;
+  }
+}
+
+export function resolveGateHostBinary({
+  platform = process.platform,
+  arch = process.arch,
+  searchFrom = process.cwd(),
+  cacheRoot,
+  resolveCachedBinary = (opts) => resolveAndCacheHostBinary(opts),
+  resolvePackagedBinary = (opts) => resolveHostBinaryPath(opts),
+} = {}) {
+  const diagnostics = [];
+  const spec = getHostPackageSpec({ platform, arch });
+  const binaryName = basename(spec.binaryRelativePath);
+  const repoRoot = findRepoRootWithRustHost(searchFrom);
+  const localCandidates = repoRoot ? resolveLocalHostBinaryCandidates(repoRoot, binaryName) : [];
+
+  for (const candidate of localCandidates) {
+    if (!existsSync(candidate)) continue;
+    if (!canExecuteFile(candidate)) {
+      diagnostics.push(`Detected local host binary but it is not executable: ${candidate}`);
+      continue;
+    }
+
+    return {
+      ...spec,
+      binaryPath: candidate,
+      packageRoot: dirname(candidate),
+      source: 'local-build',
+      diagnostics,
+      localBuild: {
+        repoRoot,
+        checked: localCandidates,
+      },
+      resolvedAt: new Date().toISOString(),
+    };
+  }
+
+  const buildHint = repoRoot
+    ? `Missing local host build. Build one with: (cd ${repoRoot} && npm run build:rust)`
+    : 'Missing local host build. Build one with: npm run build:rust (from the aurascript package root).';
+  diagnostics.push(buildHint);
+
+  try {
+    const cached = resolveCachedBinary({ platform, arch, ...(cacheRoot ? { cacheRoot } : {}) });
+    return {
+      ...cached,
+      source: cached.override ? 'override' : 'cache',
+      diagnostics: [...diagnostics, ...(cached.diagnostics || [])],
+      localBuild: {
+        repoRoot,
+        checked: localCandidates,
+      },
+      resolvedAt: new Date().toISOString(),
+    };
+  } catch (cacheError) {
+    diagnostics.push(`Cache fallback unavailable: ${cacheError.message || String(cacheError)}`);
+  }
+
+  const packaged = resolvePackagedBinary({ platform, arch });
+  return {
+    ...packaged,
+    source: 'package',
+    diagnostics,
+    localBuild: {
+      repoRoot,
+      checked: localCandidates,
+    },
+    resolvedAt: new Date().toISOString(),
+  };
+}
+
+export function listSupportedHostTargets() {
+  return HOST_PACKAGE_SPECS.map((spec) => Object.freeze({
+    platform: spec.platform,
+    arch: spec.arch,
+    target: spec.target,
+    packageName: spec.packageName,
+    binaryRelativePath: spec.binaryRelativePath,
+  }));
+}

package/src/perf-benchmark-runner.mjs

@@ -0,0 +1,233 @@
+#!/usr/bin/env node
+
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+
+import {
+  DEFAULT_PERF_EVALUATION_PATH,
+  evaluatePerfReport,
+  loadPerfThresholds,
+  runPerfBenchmarks,
+} from './perf-benchmark.mjs';
+
+function parseCliArgs(argv) {
+  let strict = false;
+  let repeats = 5;
+  let thresholdPath = null;
+  let reportPath = null;
+  let workspaceRoot = null;
+  let evaluationPath = DEFAULT_PERF_EVALUATION_PATH;
+  let assetMode = null;
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const token = argv[i];
+    if (token === '--strict') {
+      strict = true;
+      continue;
+    }
+    if (token === '--repeats' && argv[i + 1]) {
+      repeats = Number.parseInt(argv[i + 1], 10);
+      i += 1;
+      continue;
+    }
+    if (token === '--thresholds' && argv[i + 1]) {
+      thresholdPath = argv[i + 1];
+      i += 1;
+      continue;
+    }
+    if (token === '--report-path' && argv[i + 1]) {
+      reportPath = argv[i + 1];
+      i += 1;
+      continue;
+    }
+    if (token === '--workspace-root' && argv[i + 1]) {
+      workspaceRoot = argv[i + 1];
+      i += 1;
+      continue;
+    }
+    if (token === '--evaluation-path' && argv[i + 1]) {
+      evaluationPath = argv[i + 1];
+      i += 1;
+      continue;
+    }
+    if (token === '--asset-mode' && argv[i + 1]) {
+      assetMode = argv[i + 1];
+      i += 1;
+      continue;
+    }
+    throw new Error(`Unknown benchmark option: ${token}`);
+  }
+
+  if (!Number.isInteger(repeats) || repeats < 1) {
+    throw new Error('--repeats must be a positive integer');
+  }
+  if (strict && repeats < 2) {
+    throw new Error('--strict requires --repeats >= 2 to evaluate warm-cache thresholds');
+  }
+
+  return {
+    strict,
+    repeats,
+    thresholdPath,
+    reportPath,
+    workspaceRoot,
+    assetMode,
+    evaluationPath: resolve(process.cwd(), evaluationPath),
+  };
+}
+
+function mapApplicableScenes(report, sceneThresholds = {}) {
+  const reportSceneIds = new Set((report?.scenes || []).map((scene) => scene.id));
+  return Object.entries(sceneThresholds)
+    .filter(([sceneId]) => reportSceneIds.has(sceneId))
+    .map(([sceneId, limits]) => ({
+      id: sceneId,
+      maxAvgFrameTimeMs: limits.maxAvgFrameTimeMs,
+      maxJitterMs: limits.maxJitterMs,
+      minFps: limits.minFps,
+      maxP50FrameTimeMs: limits.maxP50FrameTimeMs,
+      maxP95FrameTimeMs: limits.maxP95FrameTimeMs,
+      maxP99FrameTimeMs: limits.maxP99FrameTimeMs,
+      maxStutterBurstCount: limits.maxStutterBurstCount,
+    }));
+}
+
+function bucketFailures(failures) {
+  return {
+    coldStart: failures.filter((entry) => String(entry.type || '').startsWith('coldStart.')),
+    warmCache: failures.filter((entry) => String(entry.type || '').startsWith('warmCache.')),
+    other: failures.filter((entry) => !String(entry.type || '').startsWith('coldStart.') && !String(entry.type || '').startsWith('warmCache.')),
+  };
+}
+
+function buildThresholdContext(report, thresholds, thresholdPath) {
+  const thresholdScenes = thresholds?.scenes || {};
+  return {
+    path: thresholdPath,
+    schemaVersion: thresholds?.schemaVersion || null,
+    scenePolicy: thresholds?.scenePolicy || null,
+    sceneCount: Object.keys(thresholdScenes).length,
+    applicableScenes: mapApplicableScenes(report, thresholdScenes),
+    coldStart: {
+      applicableScenes: mapApplicableScenes(report, thresholds?.coldStart?.scenes || {}),
+    },
+    warmCache: {
+      applicableScenes: mapApplicableScenes(report, thresholds?.warmCache?.scenes || {}),
+    },
+    latency: thresholds?.latency || null,
+  };
+}
+
+function writeEvaluationArtifact(artifactPath, artifact) {
+  mkdirSync(dirname(artifactPath), { recursive: true });
+  writeFileSync(artifactPath, `${JSON.stringify(artifact, null, 2)}\n`, 'utf8');
+}
+
+try {
+  const {
+    strict,
+    repeats,
+    thresholdPath,
+    reportPath,
+    workspaceRoot,
+    assetMode,
+    evaluationPath,
+  } = parseCliArgs(process.argv.slice(2));
+  const report = await runPerfBenchmarks({
+    projectRoot: process.cwd(),
+    repeats,
+    reportPath,
+    workspaceRoot,
+    assetMode,
+  });
+  const { path: resolvedThresholdPath, thresholds } = loadPerfThresholds(thresholdPath);
+  const failures = evaluatePerfReport(report, thresholds);
+  const failureBuckets = bucketFailures(failures);
+  const status = strict && failures.length > 0 ? 'fail' : 'pass';
+  const evaluationArtifact = {
+    generatedAt: new Date().toISOString(),
+    status,
+    strict,
+    repeats,
+    thresholdPath: resolvedThresholdPath,
+    thresholdContext: buildThresholdContext(report, thresholds, resolvedThresholdPath),
+    reportPath: report.reportPath,
+    hostBinary: report.hostBinary || null,
+    assetMode: report?.config?.assetMode || null,
+    runtimeCacheDiagnostics: report.runtimeCacheDiagnostics || null,
+    failureCount: failures.length,
+    failureBuckets: {
+      coldStart: {
+        count: failureBuckets.coldStart.length,
+        failures: failureBuckets.coldStart,
+      },
+      warmCache: {
+        count: failureBuckets.warmCache.length,
+        failures: failureBuckets.warmCache,
+      },
+      other: {
+        count: failureBuckets.other.length,
+        failures: failureBuckets.other,
+      },
+    },
+    failures,
+  };
+
+  writeEvaluationArtifact(evaluationPath, evaluationArtifact);
+
+  console.log('');
+  console.log('  aura benchmark: complete');
+  console.log(`  Report: ${report.reportPath}`);
+  console.log(`  Thresholds: ${resolvedThresholdPath}`);
+  console.log(`  Threshold evaluation: ${evaluationPath}`);
+  if (report.hostBinary) {
+    console.log(`  Host binary source: ${report.hostBinary.source || 'unknown'}`);
+    console.log(`  Host binary path: ${report.hostBinary.path}`);
+    for (const diagnostic of report.hostBinary.diagnostics || []) {
+      console.log(`  Host diagnostic: ${diagnostic}`);
+    }
+  }
+
+  for (const scene of report.scenes) {
+    console.log(`  Scene ${scene.id}: avgFrameTime=${scene.avgFrameTimeMs.toFixed(4)}ms jitter=${scene.jitterMs.toFixed(4)}ms avgFps=${scene.avgFps.toFixed(2)}`);
+    if (scene.coldStart) {
+      console.log(`    coldStart: avgFrameTime=${scene.coldStart.avgFrameTimeMs.toFixed(4)}ms jitter=${scene.coldStart.jitterMs.toFixed(4)}ms avgFps=${scene.coldStart.avgFps.toFixed(2)} samples=${scene.coldStart.sampleCount}`);
+    }
+    if (scene.warmCache) {
+      console.log(`    warmCache: avgFrameTime=${scene.warmCache.avgFrameTimeMs.toFixed(4)}ms jitter=${scene.warmCache.jitterMs.toFixed(4)}ms avgFps=${scene.warmCache.avgFps.toFixed(2)} samples=${scene.warmCache.sampleCount}`);
+    }
+  }
+
+  console.log(`  Synthetic latency: input=${report.latency.inputQueryMs.toFixed(6)}ms audio=${report.latency.audioCallMs.toFixed(6)}ms`);
+
+  if (failures.length > 0) {
+    console.log('');
+    console.log(`  Threshold failures: ${failures.length}`);
+    console.log(`    coldStart: ${failureBuckets.coldStart.length}`);
+    console.log(`    warmCache: ${failureBuckets.warmCache.length}`);
+    console.log(`    other: ${failureBuckets.other.length}`);
+    for (const failure of failures) {
+      if (failure.scene) {
+        console.log(`    - ${failure.type} (${failure.scene}): actual=${failure.actual} threshold=${failure.threshold}`);
+      } else {
+        console.log(`    - ${failure.type}: actual=${failure.actual} threshold=${failure.threshold}`);
+      }
+    }
+
+    if (strict) {
+      console.log('');
+      console.log('  aura benchmark: FAIL (strict mode)');
+      console.log('');
+      process.exit(1);
+    }
+  }
+
+  console.log('');
+  console.log('  aura benchmark: PASS');
+  console.log('');
+} catch (error) {
+  console.error('');
+  console.error(`  aura benchmark error: ${error.message}`);
+  console.error('');
+  process.exit(1);
+}