@auraindustry/aurajs 0.1.1 → 0.1.5

package/src/bin-integrity.mjs

@@ -1,4 +1,3 @@
-import { createHash } from 'node:crypto';
 import { existsSync, readdirSync, readFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -28,14 +27,37 @@ 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'));
 }
 
+const PLAY_WRAPPER_REQUIRED_MARKERS = [
+  '#!/usr/bin/env node',
+  'const fallbackAuraPackage =',
+  "const MINIMAL_COMMANDS = ['dev', 'join', 'play', 'fork', 'publish', 'session'];",
+  "const ALL_COMMANDS = ['dev', 'join', 'play', 'fork', 'publish', 'session', 'state', 'inspect', 'action'];",
+  "args: ['exec', '--yes', '--package', fallbackAuraPackage, '--', 'aura', ...commandArgs]",
+];
+
+function assertPlayWrapperContract(relativePath, fileContent) {
+  const normalized = normalizeText(fileContent);
+  const missingMarkers = PLAY_WRAPPER_REQUIRED_MARKERS.filter((marker) => !normalized.includes(marker));
+  if (missingMarkers.length > 0) {
+    throw new ProjectBinIntegrityError(
+      'project_bin_wrapper_contract_invalid',
+      `Bin target "${relativePath}" does not satisfy the AuraJS play wrapper contract.`,
+      {
+        relativePath,
+        missingMarkers,
+      },
+    );
+  }
+
+  return {
+    markers: [...PLAY_WRAPPER_REQUIRED_MARKERS],
+  };
+}
+
 function listRelativeFiles(root, current = root, acc = []) {
   for (const entry of readdirSync(current, { withFileTypes: true })) {
     const fullPath = join(current, entry.name);
@@ -84,6 +106,7 @@ export function assertProjectBinIntegrity(
     aurajsPackageRoot = DEFAULT_AURAJS_PACKAGE_ROOT,
     expectedAurajsVersion = null,
     enforceExactAurajsDependency = true,
+    enforceResolvedAurajsVersionMatch = false,
   } = {},
 ) {
   const resolvedProjectRoot = resolve(projectRoot || process.cwd());
@@ -146,7 +169,7 @@ export function assertProjectBinIntegrity(
 
   const aurajsPackage = readJsonFile(aurajsPackageJsonPath);
   const resolvedAurajsVersion = String(aurajsPackage?.version || '').trim();
-  if (expectedAurajsVersion && resolvedAurajsVersion !== expectedAurajsVersion) {
+  if (enforceResolvedAurajsVersionMatch && expectedAurajsVersion && resolvedAurajsVersion !== expectedAurajsVersion) {
     throw new ProjectBinIntegrityError(
       'project_aurajs_resolved_version_mismatch',
       `Resolved @auraindustry/aurajs ${resolvedAurajsVersion || '<missing>'}, expected ${expectedAurajsVersion}.`,
@@ -167,9 +190,6 @@ export function assertProjectBinIntegrity(
     );
   }
 
-  const canonicalTemplate = normalizeText(readFileSync(templatePath, 'utf8'));
-  const canonicalTemplateHash = sha256Text(canonicalTemplate);
-
   const binEntries = resolveProjectBinEntries(resolvedProjectPackage, resolvedPackageName);
   if (binEntries.length === 0) {
     throw new ProjectBinIntegrityError(
@@ -227,26 +247,13 @@ export function assertProjectBinIntegrity(
       );
     }
 
-    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,
-        },
-      );
-    }
+    const fileContent = readFileSync(absolutePath, 'utf8');
+    const wrapperContract = assertPlayWrapperContract(relativePath, fileContent);
 
     verifiedFiles.push({
       relativePath,
       absolutePath,
-      hash: fileHash,
+      wrapperContract,
     });
   }
 
@@ -260,7 +267,7 @@ export function assertProjectBinIntegrity(
       resolvedVersion: resolvedAurajsVersion,
       packageRoot: aurajsPackageRoot,
       templatePath,
-      templateHash: canonicalTemplateHash,
+      wrapperContract: 'aurajs.play-wrapper.v1',
     },
     bin: {
       entries: binEntries,

package/src/build-contract/capabilities.mjs

@@ -2,11 +2,44 @@ import { existsSync, readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 
 import {
+  MOBILE_CAPABILITY_REPORT_SCHEMA,
   PROJECT_CAPABILITY_DECLARATION_FILE,
   WEB_CAPABILITY_DECLARATION_SCHEMA,
   WEB_RUNTIME_CONFIG_SCHEMA,
 } from './constants.mjs';
 import { normalizePositiveInt } from './helpers.mjs';
+import { buildMobileCapabilityReport } from '../mobile/shared/capabilities.mjs';
+
+const MOBILE_UNSUPPORTED_API_RULES = Object.freeze([
+  Object.freeze({
+    api: 'aura.window.setCursorLocked',
+    reasonCode: 'mobile_cursor_lock_unsupported',
+  }),
+  Object.freeze({
+    api: 'aura.input.getMouseDelta',
+    reasonCode: 'mobile_cursor_lock_unsupported',
+  }),
+  Object.freeze({
+    api: 'aura.input.getMouseWheel',
+    reasonCode: 'mobile_mouse_wheel_unsupported',
+  }),
+  Object.freeze({
+    api: 'aura.window.setSize',
+    reasonCode: 'mobile_window_management_unsupported',
+  }),
+  Object.freeze({
+    api: 'aura.window.setFullscreen',
+    reasonCode: 'mobile_window_management_unsupported',
+  }),
+  Object.freeze({
+    api: 'aura.window.setTitle',
+    reasonCode: 'mobile_window_management_unsupported',
+  }),
+  Object.freeze({
+    api: 'aura.window.setCursorVisible',
+    reasonCode: 'mobile_window_management_unsupported',
+  }),
+]);
 
 export function buildRuntimeConfig(options = {}) {
   const windowConfig = options.windowConfig && typeof options.windowConfig === 'object'
@@ -67,6 +100,40 @@ function normalizeOptionalModules(modules) {
   };
 }
 
+function buildMobileTargetAssessment(requiredApis) {
+  const matchedApis = new Set();
+  const reasonCodes = new Set();
+
+  for (const api of requiredApis) {
+    for (const rule of MOBILE_UNSUPPORTED_API_RULES) {
+      if (api !== rule.api) continue;
+      matchedApis.add(api);
+      reasonCodes.add(rule.reasonCode);
+    }
+  }
+
+  const normalizedMatchedApis = [...matchedApis].sort((a, b) => a.localeCompare(b));
+  const normalizedReasonCodes = [...reasonCodes].sort((a, b) => a.localeCompare(b));
+  const portable = normalizedReasonCodes.length === 0;
+
+  return {
+    schema: 'aurajs.mobile-capability-assessment.v1',
+    portable,
+    matchedDesktopApis: normalizedMatchedApis,
+    unsupportedReasonCodes: normalizedReasonCodes,
+    targets: {
+      android: {
+        portable,
+        unsupportedReasonCodes: normalizedReasonCodes,
+      },
+      ios: {
+        portable,
+        unsupportedReasonCodes: normalizedReasonCodes,
+      },
+    },
+  };
+}
+
 function normalizeWebCapabilityDeclaration(value, baseModules = {}, source = null) {
   const declaration = value && typeof value === 'object' && !Array.isArray(value)
     ? value
@@ -85,16 +152,18 @@ function normalizeWebCapabilityDeclaration(value, baseModules = {}, source = nul
   }
 
   const declaredModules = normalizeOptionalModules(declaration.optionalModules);
+  const requiredApis = normalizeRequiredApis(declaration.requiredApis);
   return {
     schema: WEB_CAPABILITY_DECLARATION_SCHEMA,
     source,
-    requiredApis: normalizeRequiredApis(declaration.requiredApis),
+    requiredApis,
     optionalModules: {
       physics: baseModules.physics || declaredModules.physics,
       network: baseModules.network || declaredModules.network,
       multiplayer: baseModules.multiplayer || declaredModules.multiplayer,
       steam: baseModules.steam || declaredModules.steam,
     },
+    mobileTargetAssessment: buildMobileTargetAssessment(requiredApis),
   };
 }
 
@@ -114,3 +183,20 @@ export function readProjectCapabilityDeclaration({ projectRoot, modules }) {
 
   return normalizeWebCapabilityDeclaration(parsed, baseModules, PROJECT_CAPABILITY_DECLARATION_FILE);
 }
+
+export function buildMobileCapabilityAssertion({ projectRoot, modules, target }) {
+  const capabilityDeclaration = readProjectCapabilityDeclaration({
+    projectRoot,
+    modules,
+  });
+  const report = buildMobileCapabilityReport({
+    target,
+    capabilityDeclaration,
+  });
+  return {
+    ...report,
+    schema: MOBILE_CAPABILITY_REPORT_SCHEMA,
+  };
+}
+
+export { buildMobileCapabilityReport } from '../mobile/shared/capabilities.mjs';

package/src/build-contract/constants.mjs

@@ -2,5 +2,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 MOBILE_CAPABILITY_REPORT_SCHEMA = 'aurajs.mobile-capability-report.v1';
 
 export const PROJECT_CAPABILITY_DECLARATION_FILE = 'aura.capabilities.json';

package/src/build-contract.mjs

@@ -16,11 +16,13 @@ import { WEB_INDEX_HTML, WEB_LOADER_SOURCE } from './build-contract/web-template
 
 export {
   BUILD_MANIFEST_SCHEMA,
+  MOBILE_CAPABILITY_REPORT_SCHEMA,
   WEB_BUILD_MANIFEST_SCHEMA,
   WEB_CAPABILITY_DECLARATION_SCHEMA,
   WEB_RUNTIME_CONFIG_SCHEMA,
 } from './build-contract/constants.mjs';
 export { writeCanonicalJsonFile } from './build-contract/helpers.mjs';
+export { buildRuntimeConfig, readProjectCapabilityDeclaration } from './build-contract/capabilities.mjs';
 
 export function writeBuildManifest(options = {}) {
   const outRoot = resolve(options.outRoot || process.cwd());

package/src/bundler.mjs

@@ -1,5 +1,6 @@
 import { createHash } from 'node:crypto';
 import { spawnSync } from 'node:child_process';
+import { createRequire } from 'node:module';
 import {
   existsSync,
   mkdirSync,
@@ -9,7 +10,8 @@ import {
   readdirSync,
   watch,
 } from 'node:fs';
-import { dirname, isAbsolute, join, normalize, relative, resolve, sep } from 'node:path';
+import { dirname, extname, isAbsolute, join, normalize, relative, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { buildGameActionRuntimeBootstrapSource } from './game-action-runtime.mjs';
 import { buildStateRestoreRuntimeBootstrapSource } from './game-state-runtime.mjs';
 
@@ -42,6 +44,22 @@ const AUTHORED_SOURCE_ROOT_DIRS = Object.freeze([
   'data',
 ]);
 
+const BUNDLER_DIR = dirname(fileURLToPath(import.meta.url));
+const CLI_PACKAGE_ROOT = resolve(BUNDLER_DIR, '..');
+const CLI_PACKAGE = JSON.parse(readFileSync(resolve(CLI_PACKAGE_ROOT, 'package.json'), 'utf8'));
+const CLI_PACKAGE_NAME = CLI_PACKAGE.name;
+const SUPPORTED_HELPER_SPECIFIER = `${CLI_PACKAGE_NAME}/helpers`;
+const SELF_PACKAGE_EXPORTS = new Map(
+  Object.entries(CLI_PACKAGE.exports || {})
+    .filter(([, target]) => typeof target === 'string' && target.length > 0)
+    .map(([subpath, target]) => {
+      const packageSpecifier = subpath === '.'
+        ? CLI_PACKAGE_NAME
+        : `${CLI_PACKAGE_NAME}/${subpath.replace(/^\.\//, '')}`;
+      return [packageSpecifier, resolve(CLI_PACKAGE_ROOT, target)];
+    }),
+);
+
 export function isBundleError(error) {
   return error instanceof BundleError;
 }
@@ -78,6 +96,13 @@ export function formatBundleError(error, projectRoot = process.cwd()) {
     }
   }
 
+  if (Array.isArray(details.hints) && details.hints.length > 0) {
+    parts.push('hints:');
+    for (const hint of details.hints) {
+      parts.push(`  - ${hint}`);
+    }
+  }
+
   if (details.cycle) {
     const rendered = details.cycle.map((entry) => relPath(projectRoot, entry)).join(' -> ');
     parts.push(`cycle: ${rendered}`);
@@ -247,6 +272,7 @@ function buildModuleGraph(ctx) {
       filePath,
       code: parsed.code,
       imports: dependencies,
+      moduleType: parsed.moduleType,
     });
 
     state.set(filePath, 2);
@@ -298,6 +324,10 @@ function emitBundle(graph) {
 }
 
 function transformModule(moduleMeta, srcDir) {
+  if (moduleMeta.moduleType === 'json') {
+    return `__exports.default = ${moduleMeta.code.trim()};`;
+  }
+
   const importByLine = new Map();
   const importContinuationLines = new Set();
   for (const item of moduleMeta.imports) {
@@ -483,15 +513,23 @@ function readParsedModule(ctx, filePath) {
   const content = readFileSync(filePath, 'utf8');
   const hash = sha1(content);
   const cached = ctx.cache.files.get(filePath);
+  const moduleType = extname(filePath).toLowerCase() === '.json' ? 'json' : 'js';
 
   if (cached && cached.hash === hash) {
     return cached;
   }
 
+  if (moduleType === 'json') {
+    validateJsonModule(content, filePath);
+    const parsed = { hash, code: content, imports: [], moduleType };
+    ctx.cache.files.set(filePath, parsed);
+    return parsed;
+  }
+
   validateSyntax(content, filePath);
 
   const imports = scanImports(content, filePath);
-  const parsed = { hash, code: content, imports };
+  const parsed = { hash, code: content, imports, moduleType };
   ctx.cache.files.set(filePath, parsed);
   return parsed;
 }
@@ -559,7 +597,8 @@ function scanImports(code, filePath) {
 
 function parseImportStatement(statement) {
   const normalized = statement.replace(/\s+/g, ' ').trim();
-  const sideEffect = normalized.match(/^import\s+['"]([^'"\n]+)['"]\s*;?$/);
+  const importAttributes = String.raw`(?:\s+(?:with|assert)\s+\{[^}]*\})?`;
+  const sideEffect = normalized.match(new RegExp(`^import\\s+['"]([^'"\\n]+)['"]${importAttributes}\\s*;?$`));
   if (sideEffect) {
     return {
       clause: null,
@@ -567,7 +606,7 @@ function parseImportStatement(statement) {
     };
   }
 
-  const fromImport = normalized.match(/^import\s+(.+?)\s+from\s+['"]([^'"\n]+)['"]\s*;?$/);
+  const fromImport = normalized.match(new RegExp(`^import\\s+(.+?)\\s+from\\s+['"]([^'"\\n]+)['"]${importAttributes}\\s*;?$`));
   if (fromImport) {
     return {
       clause: fromImport[1].trim(),
@@ -582,15 +621,12 @@ function resolveSpecifier(projectRoot, allowedSourceRoots, srcDir, importer, imp
   const specifier = importEntry.specifier;
 
   if (!(specifier.startsWith('./') || specifier.startsWith('../'))) {
-    throw new BundleError(
-      BUNDLE_ERROR_CODES.UNSUPPORTED_SPECIFIER,
-      `Unsupported module specifier "${specifier}". Use relative imports only.`,
-      {
-        file: importer,
-        importer,
-        specifier,
-        line: importEntry.line,
-      },
+    return resolveSupportedPackageSpecifier(
+      projectRoot,
+      allowedSourceRoots,
+      srcDir,
+      importer,
+      importEntry,
     );
   }
 
@@ -623,6 +659,60 @@ function resolveSpecifier(projectRoot, allowedSourceRoots, srcDir, importer, imp
   );
 }
 
+function resolveSupportedPackageSpecifier(projectRoot, allowedSourceRoots, srcDir, importer, importEntry) {
+  const specifier = importEntry.specifier;
+  let resolved = null;
+  let packageRoot = null;
+
+  if (specifier === CLI_PACKAGE_NAME || specifier.startsWith(`${CLI_PACKAGE_NAME}/`)) {
+    try {
+      resolved = createRequire(importer).resolve(specifier);
+    } catch {
+      resolved = null;
+    }
+
+    if (!resolved && SELF_PACKAGE_EXPORTS.has(specifier)) {
+      resolved = SELF_PACKAGE_EXPORTS.get(specifier);
+      packageRoot = CLI_PACKAGE_ROOT;
+    }
+  }
+
+  if (!resolved) {
+    throw new BundleError(
+      BUNDLE_ERROR_CODES.UNSUPPORTED_SPECIFIER,
+      `Unsupported module specifier "${specifier}".`,
+      {
+        file: importer,
+        importer,
+        specifier,
+        line: importEntry.line,
+        hints: [
+          'Use relative imports for authored project files.',
+          `Use the local src/starter-utils copy or supported package imports from "${SUPPORTED_HELPER_SPECIFIER}".`,
+        ],
+      },
+    );
+  }
+
+  if (!(existsSync(resolved) && statSync(resolved).isFile())) {
+    throw new BundleError(
+      BUNDLE_ERROR_CODES.MODULE_NOT_FOUND,
+      `Module not found for specifier "${specifier}".`,
+      {
+        file: importer,
+        importer,
+        specifier,
+        line: importEntry.line,
+        candidates: [relPath(srcDir, resolved)],
+      },
+    );
+  }
+
+  packageRoot ||= findNearestPackageRoot(resolved) || CLI_PACKAGE_ROOT;
+  appendAllowedRoot(allowedSourceRoots, packageRoot);
+  return resolved;
+}
+
 function resolveAllowedSourceRoots(projectRoot, explicitRoots = null) {
   if (Array.isArray(explicitRoots) && explicitRoots.length > 0) {
     return explicitRoots
@@ -640,6 +730,28 @@ function resolveAllowedSourceRoots(projectRoot, explicitRoots = null) {
   return roots;
 }
 
+function appendAllowedRoot(allowedSourceRoots, root) {
+  const normalizedRoot = resolve(root);
+  if (!allowedSourceRoots.some((candidate) => candidate === normalizedRoot)) {
+    allowedSourceRoots.push(normalizedRoot);
+  }
+}
+
+function findNearestPackageRoot(filePath) {
+  let current = dirname(filePath);
+  while (true) {
+    const packageJsonPath = join(current, 'package.json');
+    if (existsSync(packageJsonPath) && statSync(packageJsonPath).isFile()) {
+      return current;
+    }
+    const parent = resolve(current, '..');
+    if (parent === current) {
+      return null;
+    }
+    current = parent;
+  }
+}
+
 function ensureEntryWithinSource(projectRoot, allowedSourceRoots, entryFile) {
   if (allowedSourceRoots.some((root) => pathIsWithinRoot(root, entryFile))) {
     return;
@@ -651,6 +763,10 @@ function ensureEntryWithinSource(projectRoot, allowedSourceRoots, entryFile) {
     {
       file: entryFile,
       candidates: allowedSourceRoots.map((root) => relPath(projectRoot, root)),
+      hints: [
+        'Entrypoints must stay inside the authored project source roots.',
+        `Use "${SUPPORTED_HELPER_SPECIFIER}" through local src/starter-utils copies for shared helper code instead of moving entrypoints outside src/.`,
+      ],
     },
   );
 }
@@ -674,6 +790,10 @@ function ensureWithinSource(projectRoot, allowedSourceRoots, candidate, importer
       specifier: importEntry.specifier,
       line: importEntry.line,
       candidates: allowedSourceRoots.map((root) => relPath(projectRoot, root)),
+      hints: [
+        'Move shared authored helper code into src/ if it is project-specific.',
+        `For supported shared helper lanes, import from "${SUPPORTED_HELPER_SPECIFIER}" or keep the local src/starter-utils copy.`,
+      ],
     },
   );
 }
@@ -710,6 +830,16 @@ function validateSyntax(code, filePath) {
   });
 }
 
+function validateJsonModule(code, filePath) {
+  try {
+    JSON.parse(code);
+  } catch {
+    throw new BundleError(BUNDLE_ERROR_CODES.SYNTAX_ERROR, 'Invalid JSON module.', {
+      file: filePath,
+    });
+  }
+}
+
 function hasDynamicImport(code) {
   return /(^|[^\w$.])import\s*\(/m.test(code);
 }