@auraindustry/aurajs 0.0.7 → 0.1.1

package/src/bin-integrity.mjs

@@ -0,0 +1,272 @@
+import { createHash } from 'node:crypto';
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export const DEFAULT_AURAJS_PACKAGE_ROOT = dirname(fileURLToPath(new URL('../package.json', import.meta.url)));
+export const EXACT_SEMVER_PATTERN = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+
+export class ProjectBinIntegrityError extends Error {
+  constructor(reasonCode, message, details = {}) {
+    super(message);
+    this.name = 'ProjectBinIntegrityError';
+    this.reasonCode = typeof reasonCode === 'string' && reasonCode.length > 0
+      ? reasonCode
+      : 'project_bin_integrity_failed';
+    this.details = details && typeof details === 'object' ? details : {};
+  }
+}
+
+function normalizeRelativePath(pathLike) {
+  return String(pathLike || '')
+    .trim()
+    .replace(/^[.][\\/]/, '')
+    .replaceAll('\\', '/');
+}
+
+function normalizeText(value) {
+  return String(value || '').replace(/\r\n?/g, '\n');
+}
+
+function sha256Text(value) {
+  return createHash('sha256').update(normalizeText(value)).digest('hex');
+}
+
+function readJsonFile(path) {
+  return JSON.parse(readFileSync(path, 'utf8'));
+}
+
+function listRelativeFiles(root, current = root, acc = []) {
+  for (const entry of readdirSync(current, { withFileTypes: true })) {
+    const fullPath = join(current, entry.name);
+    if (entry.isDirectory()) {
+      listRelativeFiles(root, fullPath, acc);
+      continue;
+    }
+    if (entry.isFile()) {
+      acc.push(normalizeRelativePath(fullPath.slice(root.length + 1)));
+    }
+  }
+  return acc;
+}
+
+export function isExactSemver(value) {
+  return EXACT_SEMVER_PATTERN.test(String(value || '').trim());
+}
+
+export function resolveProjectBinEntries(projectPackage, packageName = null) {
+  const normalizedPackageName = typeof packageName === 'string' && packageName.trim().length > 0
+    ? packageName.trim()
+    : (typeof projectPackage?.name === 'string' && projectPackage.name.trim().length > 0
+      ? projectPackage.name.trim()
+      : null);
+
+  if (typeof projectPackage?.bin === 'string' && projectPackage.bin.trim().length > 0) {
+    return [{
+      name: normalizedPackageName?.split('/').pop() || normalizedPackageName || 'game',
+      relativePath: normalizeRelativePath(projectPackage.bin.trim()),
+    }];
+  }
+
+  return Object.entries(projectPackage?.bin || {})
+    .filter(([, value]) => typeof value === 'string' && value.trim().length > 0)
+    .map(([name, value]) => ({
+      name,
+      relativePath: normalizeRelativePath(value.trim()),
+    }));
+}
+
+export function assertProjectBinIntegrity(
+  {
+    projectRoot,
+    projectPackage = null,
+    packageName = null,
+    aurajsPackageRoot = DEFAULT_AURAJS_PACKAGE_ROOT,
+    expectedAurajsVersion = null,
+    enforceExactAurajsDependency = true,
+  } = {},
+) {
+  const resolvedProjectRoot = resolve(projectRoot || process.cwd());
+  const packagePath = resolve(resolvedProjectRoot, 'package.json');
+  if (!existsSync(packagePath)) {
+    throw new ProjectBinIntegrityError(
+      'project_package_json_missing',
+      'Project bin integrity check requires a package.json in the current project root.',
+      { packagePath },
+    );
+  }
+
+  const resolvedProjectPackage = projectPackage || readJsonFile(packagePath);
+  const resolvedPackageName = typeof packageName === 'string' && packageName.trim().length > 0
+    ? packageName.trim()
+    : (typeof resolvedProjectPackage?.name === 'string' && resolvedProjectPackage.name.trim().length > 0
+      ? resolvedProjectPackage.name.trim()
+      : null);
+
+  const dependencySpec = String(resolvedProjectPackage?.dependencies?.['@auraindustry/aurajs'] || '').trim();
+  if (!dependencySpec) {
+    throw new ProjectBinIntegrityError(
+      'project_aurajs_dependency_missing',
+      'Published AuraJS games must depend on @auraindustry/aurajs.',
+      { packagePath },
+    );
+  }
+
+  if (enforceExactAurajsDependency && !isExactSemver(dependencySpec)) {
+    throw new ProjectBinIntegrityError(
+      'project_aurajs_dependency_unpinned',
+      'Published AuraJS games must pin @auraindustry/aurajs to an exact version.',
+      {
+        dependencySpec,
+        packagePath,
+      },
+    );
+  }
+
+  if (expectedAurajsVersion && dependencySpec !== expectedAurajsVersion) {
+    throw new ProjectBinIntegrityError(
+      'project_aurajs_dependency_version_mismatch',
+      `Expected @auraindustry/aurajs version ${expectedAurajsVersion}, found ${dependencySpec}.`,
+      {
+        dependencySpec,
+        expectedAurajsVersion,
+        packagePath,
+      },
+    );
+  }
+
+  const aurajsPackageJsonPath = resolve(aurajsPackageRoot, 'package.json');
+  if (!existsSync(aurajsPackageJsonPath)) {
+    throw new ProjectBinIntegrityError(
+      'project_aurajs_package_missing',
+      'Could not resolve the canonical @auraindustry/aurajs package used for bin verification.',
+      { aurajsPackageJsonPath },
+    );
+  }
+
+  const aurajsPackage = readJsonFile(aurajsPackageJsonPath);
+  const resolvedAurajsVersion = String(aurajsPackage?.version || '').trim();
+  if (expectedAurajsVersion && resolvedAurajsVersion !== expectedAurajsVersion) {
+    throw new ProjectBinIntegrityError(
+      'project_aurajs_resolved_version_mismatch',
+      `Resolved @auraindustry/aurajs ${resolvedAurajsVersion || '<missing>'}, expected ${expectedAurajsVersion}.`,
+      {
+        resolvedAurajsVersion,
+        expectedAurajsVersion,
+        aurajsPackageJsonPath,
+      },
+    );
+  }
+
+  const templatePath = resolve(aurajsPackageRoot, 'templates', 'create-bin', 'play.js');
+  if (!existsSync(templatePath)) {
+    throw new ProjectBinIntegrityError(
+      'project_play_template_missing',
+      'Could not find the canonical AuraJS play.js template for bin verification.',
+      { templatePath },
+    );
+  }
+
+  const canonicalTemplate = normalizeText(readFileSync(templatePath, 'utf8'));
+  const canonicalTemplateHash = sha256Text(canonicalTemplate);
+
+  const binEntries = resolveProjectBinEntries(resolvedProjectPackage, resolvedPackageName);
+  if (binEntries.length === 0) {
+    throw new ProjectBinIntegrityError(
+      'project_bin_missing',
+      'Published AuraJS games must declare a generated wrapper entrypoint in package.json -> bin.',
+      { packagePath },
+    );
+  }
+
+  for (const entry of binEntries) {
+    if (!entry.relativePath.startsWith('bin/')) {
+      throw new ProjectBinIntegrityError(
+        'project_bin_path_outside_bin_dir',
+        `Bin target "${entry.relativePath}" must live under bin/.`,
+        { entry },
+      );
+    }
+  }
+
+  const binDir = resolve(resolvedProjectRoot, 'bin');
+  if (!existsSync(binDir)) {
+    throw new ProjectBinIntegrityError(
+      'project_bin_dir_missing',
+      'Published AuraJS games must include a bin/ directory.',
+      { binDir },
+    );
+  }
+
+  const actualBinFiles = listRelativeFiles(binDir).map((relativePath) => normalizeRelativePath(join('bin', relativePath)));
+  const declaredBinPaths = [...new Set(binEntries.map((entry) => entry.relativePath))];
+  const declaredBinSet = new Set(declaredBinPaths);
+  const unexpectedFiles = actualBinFiles.filter((relativePath) => !declaredBinSet.has(relativePath));
+  if (unexpectedFiles.length > 0) {
+    throw new ProjectBinIntegrityError(
+      'project_bin_unexpected_file',
+      `Published AuraJS games may not ship extra bin/ files: ${unexpectedFiles.join(', ')}`,
+      {
+        declaredBinPaths,
+        unexpectedFiles,
+      },
+    );
+  }
+
+  const verifiedFiles = [];
+  for (const relativePath of declaredBinPaths) {
+    const absolutePath = resolve(resolvedProjectRoot, relativePath);
+    if (!existsSync(absolutePath)) {
+      throw new ProjectBinIntegrityError(
+        'project_bin_target_missing',
+        `Bin target "${relativePath}" is missing from the project root.`,
+        {
+          relativePath,
+          absolutePath,
+        },
+      );
+    }
+
+    const fileContent = normalizeText(readFileSync(absolutePath, 'utf8'));
+    const fileHash = sha256Text(fileContent);
+    if (fileContent !== canonicalTemplate) {
+      throw new ProjectBinIntegrityError(
+        'project_bin_template_modified',
+        `Bin target "${relativePath}" does not match the canonical AuraJS play.js template.`,
+        {
+          relativePath,
+          absolutePath,
+          expectedTemplatePath: templatePath,
+          expectedTemplateHash: canonicalTemplateHash,
+          actualHash: fileHash,
+        },
+      );
+    }
+
+    verifiedFiles.push({
+      relativePath,
+      absolutePath,
+      hash: fileHash,
+    });
+  }
+
+  return {
+    reasonCode: 'project_bin_integrity_ok',
+    projectRoot: resolvedProjectRoot,
+    packagePath,
+    packageName: resolvedPackageName,
+    aurajsDependency: {
+      spec: dependencySpec,
+      resolvedVersion: resolvedAurajsVersion,
+      packageRoot: aurajsPackageRoot,
+      templatePath,
+      templateHash: canonicalTemplateHash,
+    },
+    bin: {
+      entries: binEntries,
+      declaredFiles: declaredBinPaths,
+      actualFiles: actualBinFiles,
+      verifiedFiles,
+    },
+  };
+}

package/src/build-contract/assets.mjs

@@ -0,0 +1,130 @@
+import {
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  rmSync,
+  statSync,
+} from 'node:fs';
+import { extname, relative, resolve } from 'node:path';
+
+import { sha256, toPosix } from './helpers.mjs';
+
+export function emitWebAssets({ projectRoot, outRoot }) {
+  const sourceRoot = resolve(projectRoot, 'assets');
+  const assetsOutRoot = resolve(outRoot, 'assets');
+  rmSync(assetsOutRoot, { recursive: true, force: true });
+  mkdirSync(assetsOutRoot, { recursive: true });
+
+  const sourceFiles = collectFiles(sourceRoot);
+  const entries = [];
+  for (const sourcePath of sourceFiles) {
+    const sourceRelative = toPosix(relative(sourceRoot, sourcePath));
+    const sourceBytes = readFileSync(sourcePath);
+    const contentHash = sha256(sourceBytes);
+    const relativeHash = sha256(Buffer.from(sourceRelative, 'utf8')).slice(0, 8);
+    const extension = extname(sourceRelative).toLowerCase();
+    const stemSource = extension.length > 0
+      ? sourceRelative.slice(0, sourceRelative.length - extension.length)
+      : sourceRelative;
+    const stem = sanitizeAssetStem(stemSource);
+    const outputName = `${stem}.${relativeHash}.${contentHash.slice(0, 12)}${extension}`;
+    const outputPath = resolve(assetsOutRoot, outputName);
+
+    copyFileSync(sourcePath, outputPath);
+    entries.push({
+      path: `assets/${outputName}`,
+      sourcePath: sourceRelative,
+      bytes: sourceBytes.length,
+      sha256: contentHash,
+      mediaType: mediaTypeForExtension(extension),
+    });
+  }
+
+  entries.sort((a, b) => a.path.localeCompare(b.path));
+  removeUnexpectedFiles(assetsOutRoot, new Set(entries.map((entry) => entry.path.slice('assets/'.length))));
+  return { entries, assetsOutRoot };
+}
+
+function collectFiles(rootPath) {
+  if (!existsSync(rootPath)) {
+    return [];
+  }
+  const output = [];
+  walkFiles(rootPath, output);
+  output.sort((a, b) => toPosix(a).localeCompare(toPosix(b)));
+  return output;
+}
+
+function walkFiles(dirPath, output) {
+  const names = readdirSync(dirPath).sort((a, b) => a.localeCompare(b));
+  for (const name of names) {
+    const fullPath = resolve(dirPath, name);
+    const stat = statSync(fullPath);
+    if (stat.isDirectory()) {
+      walkFiles(fullPath, output);
+      continue;
+    }
+    output.push(fullPath);
+  }
+}
+
+function sanitizeAssetStem(value) {
+  const normalized = String(value || '')
+    .replace(/[\\/]+/g, '-')
+    .replace(/[^A-Za-z0-9._-]+/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/^[-._]+|[-._]+$/g, '');
+  return normalized.length > 0 ? normalized : 'asset';
+}
+
+function mediaTypeForExtension(extension) {
+  switch (extension) {
+    case '.png':
+      return 'image/png';
+    case '.jpg':
+    case '.jpeg':
+      return 'image/jpeg';
+    case '.gif':
+      return 'image/gif';
+    case '.webp':
+      return 'image/webp';
+    case '.wav':
+      return 'audio/wav';
+    case '.ogg':
+      return 'audio/ogg';
+    case '.mp3':
+      return 'audio/mpeg';
+    case '.mp4':
+      return 'video/mp4';
+    case '.ttf':
+      return 'font/ttf';
+    case '.otf':
+      return 'font/otf';
+    case '.woff':
+      return 'font/woff';
+    case '.woff2':
+      return 'font/woff2';
+    case '.json':
+      return 'application/json';
+    case '.txt':
+    case '.md':
+    case '.csv':
+      return 'text/plain; charset=utf-8';
+    default:
+      return 'application/octet-stream';
+  }
+}
+
+function removeUnexpectedFiles(rootPath, allowedNames) {
+  if (!existsSync(rootPath)) {
+    return;
+  }
+  for (const name of readdirSync(rootPath)) {
+    if (allowedNames.has(name)) {
+      continue;
+    }
+    rmSync(resolve(rootPath, name), { recursive: true, force: true });
+  }
+}

package/src/build-contract/capabilities.mjs

@@ -0,0 +1,116 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+import {
+  PROJECT_CAPABILITY_DECLARATION_FILE,
+  WEB_CAPABILITY_DECLARATION_SCHEMA,
+  WEB_RUNTIME_CONFIG_SCHEMA,
+} from './constants.mjs';
+import { normalizePositiveInt } from './helpers.mjs';
+
+export function buildRuntimeConfig(options = {}) {
+  const windowConfig = options.windowConfig && typeof options.windowConfig === 'object'
+    ? options.windowConfig
+    : {};
+  const modules = options.modules && typeof options.modules === 'object'
+    ? options.modules
+    : {};
+  const capabilityDeclaration = normalizeWebCapabilityDeclaration(
+    options.capabilityDeclaration,
+    normalizeOptionalModules(modules),
+    options.capabilityDeclaration && typeof options.capabilityDeclaration === 'object'
+      ? options.capabilityDeclaration.source || null
+      : null,
+  );
+
+  return {
+    schema: WEB_RUNTIME_CONFIG_SCHEMA,
+    schemaVersion: '1.0.0',
+    canvas: {
+      id: 'aura-canvas',
+      resizeMode: 'fit-container',
+      width: normalizePositiveInt(windowConfig.width, 1280),
+      height: normalizePositiveInt(windowConfig.height, 720),
+      devicePixelRatioMode: 'clamped',
+    },
+    loop: {
+      tickMode: 'raf',
+      maxDeltaMs: 50,
+    },
+    modules: {
+      physics: modules.physics === true,
+      network: modules.network === true,
+      multiplayer: modules.multiplayer === true,
+    },
+    capabilities: capabilityDeclaration,
+  };
+}
+
+function normalizeRequiredApis(entries) {
+  if (!Array.isArray(entries)) {
+    return [];
+  }
+  return [...new Set(entries
+    .filter((entry) => typeof entry === 'string')
+    .map((entry) => entry.trim())
+    .filter(Boolean))]
+    .sort((a, b) => a.localeCompare(b));
+}
+
+function normalizeOptionalModules(modules) {
+  const source = modules && typeof modules === 'object' ? modules : {};
+  return {
+    physics: source.physics === true,
+    network: source.network === true || source.net === true,
+    multiplayer: source.multiplayer === true,
+    steam: source.steam === true,
+  };
+}
+
+function normalizeWebCapabilityDeclaration(value, baseModules = {}, source = null) {
+  const declaration = value && typeof value === 'object' && !Array.isArray(value)
+    ? value
+    : {};
+  if (
+    declaration.schema != null
+    && declaration.schema !== 'aurajs.create-capabilities.v1'
+    && declaration.schema !== 'aurajs.capability-declaration.v1'
+    && declaration.schema !== WEB_CAPABILITY_DECLARATION_SCHEMA
+  ) {
+    throw new Error(
+      `${source || 'Capability declaration'} must use `
+      + '`aurajs.create-capabilities.v1`, `aurajs.capability-declaration.v1`, '
+      + `or \`${WEB_CAPABILITY_DECLARATION_SCHEMA}\`.`,
+    );
+  }
+
+  const declaredModules = normalizeOptionalModules(declaration.optionalModules);
+  return {
+    schema: WEB_CAPABILITY_DECLARATION_SCHEMA,
+    source,
+    requiredApis: normalizeRequiredApis(declaration.requiredApis),
+    optionalModules: {
+      physics: baseModules.physics || declaredModules.physics,
+      network: baseModules.network || declaredModules.network,
+      multiplayer: baseModules.multiplayer || declaredModules.multiplayer,
+      steam: baseModules.steam || declaredModules.steam,
+    },
+  };
+}
+
+export function readProjectCapabilityDeclaration({ projectRoot, modules }) {
+  const declarationPath = resolve(projectRoot, PROJECT_CAPABILITY_DECLARATION_FILE);
+  const baseModules = normalizeOptionalModules(modules);
+  if (!existsSync(declarationPath)) {
+    return normalizeWebCapabilityDeclaration({}, baseModules, null);
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync(declarationPath, 'utf8'));
+  } catch (error) {
+    throw new Error(`Failed to parse ${PROJECT_CAPABILITY_DECLARATION_FILE}: ${error.message}`);
+  }
+
+  return normalizeWebCapabilityDeclaration(parsed, baseModules, PROJECT_CAPABILITY_DECLARATION_FILE);
+}

package/src/build-contract/constants.mjs

@@ -0,0 +1,6 @@
+export const BUILD_MANIFEST_SCHEMA = 'aurajs.build-manifest.v1';
+export const WEB_BUILD_MANIFEST_SCHEMA = 'aurajs.web-build-manifest.v1';
+export const WEB_RUNTIME_CONFIG_SCHEMA = 'aurajs.web-runtime-config.v1';
+export const WEB_CAPABILITY_DECLARATION_SCHEMA = 'aurajs.web-capability-declaration.v1';
+
+export const PROJECT_CAPABILITY_DECLARATION_FILE = 'aura.capabilities.json';

package/src/build-contract/helpers.mjs

@@ -0,0 +1,44 @@
+import { createHash } from 'node:crypto';
+import { writeFileSync } from 'node:fs';
+import { relative, resolve, sep } from 'node:path';
+
+export function resolveRequiredPath(pathLike, fieldName) {
+  if (typeof pathLike !== 'string' || pathLike.length === 0) {
+    throw new Error(`build contract requires a non-empty "${fieldName}" path.`);
+  }
+  return resolve(pathLike);
+}
+
+export function normalizeAssetMode(value) {
+  if (value !== 'embed' && value !== 'sibling') {
+    throw new Error(`unsupported asset mode "${value}" for build contract.`);
+  }
+  return value;
+}
+
+export function toPosix(input) {
+  return input.split(sep).join('/');
+}
+
+export function resolveOptionalRelative(outRoot, pathLike) {
+  if (typeof pathLike !== 'string' || pathLike.length === 0) {
+    return null;
+  }
+  return toPosix(relative(outRoot, resolve(pathLike)));
+}
+
+export function normalizePositiveInt(value, fallback) {
+  if (!Number.isFinite(value)) {
+    return fallback;
+  }
+  const normalized = Math.floor(value);
+  return normalized > 0 ? normalized : fallback;
+}
+
+export function writeCanonicalJsonFile(path, value) {
+  writeFileSync(path, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+}
+
+export function sha256(value) {
+  return createHash('sha256').update(value).digest('hex');
+}