@auraindustry/aurajs 0.0.1

package/src/config.mjs

@@ -0,0 +1,460 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve, join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+// ---------------------------------------------------------------------------
+// Error
+// ---------------------------------------------------------------------------
+
+export class ConfigError extends Error {
+  constructor(message, details = {}) {
+    super(message);
+    this.name = 'ConfigError';
+    this.details = details;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Legacy compatibility normalization
+// ---------------------------------------------------------------------------
+
+/**
+ * Normalize known legacy/spec-shaped config fields into the current schema.
+ *
+ * Supported legacy forms:
+ * - top-level `name` / `version` -> `identity.name` / `identity.version`
+ * - `build.icon` -> `identity.icon`
+ * - `build.targets` (ignored; build v1 uses current host target)
+ * - `modules: string[]` -> `modules: { physics, network, multiplayer, steam }`
+ */
+function normalizeLegacyConfig(raw) {
+  if (raw === null || raw === undefined) return {};
+  if (typeof raw !== 'object' || Array.isArray(raw)) return raw;
+
+  const normalized = { ...raw };
+  const legacyIdentity = {};
+
+  // Legacy metadata keys from older scaffold/spec variants.
+  if (typeof normalized.name === 'string') {
+    legacyIdentity.name = normalized.name;
+  }
+  if (typeof normalized.version === 'string') {
+    legacyIdentity.version = normalized.version;
+  }
+  delete normalized.name;
+  delete normalized.version;
+
+  if (
+    normalized.build !== null &&
+    normalized.build !== undefined &&
+    typeof normalized.build === 'object' &&
+    !Array.isArray(normalized.build)
+  ) {
+    const build = { ...normalized.build };
+    delete build.targets;
+    if (typeof build.icon === 'string') {
+      legacyIdentity.icon = build.icon;
+    }
+    delete build.icon;
+    normalized.build = build;
+  }
+
+  if (
+    normalized.identity !== null &&
+    normalized.identity !== undefined &&
+    typeof normalized.identity === 'object' &&
+    !Array.isArray(normalized.identity)
+  ) {
+    normalized.identity = {
+      ...legacyIdentity,
+      ...normalized.identity,
+    };
+  } else if (Object.keys(legacyIdentity).length > 0) {
+    normalized.identity = { ...legacyIdentity };
+  }
+
+  if (Array.isArray(normalized.modules)) {
+    const modules = {
+      physics: false,
+      network: false,
+      multiplayer: false,
+      steam: false,
+    };
+
+    for (const entry of normalized.modules) {
+      if (typeof entry !== 'string') {
+        throw new ConfigError(
+          `Invalid aura.config:\n  - modules array entries must be strings, got: ${JSON.stringify(entry)}`,
+        );
+      }
+      const key = entry.trim().toLowerCase();
+      if (key === 'physics') {
+        modules.physics = true;
+      } else if (key === 'network' || key === 'net') {
+        modules.network = true;
+      } else if (key === 'multiplayer' || key === 'mp') {
+        modules.multiplayer = true;
+      } else if (key === 'steam') {
+        modules.steam = true;
+      } else if (key.length > 0) {
+        throw new ConfigError(
+          `Invalid aura.config:\n  - Unknown module in legacy modules array: "${entry}"`,
+        );
+      }
+    }
+
+    normalized.modules = modules;
+  }
+
+  if (
+    normalized.modules !== null &&
+    normalized.modules !== undefined &&
+    typeof normalized.modules === 'object' &&
+    !Array.isArray(normalized.modules)
+  ) {
+    const modules = { ...normalized.modules };
+    if (Object.prototype.hasOwnProperty.call(modules, 'net')) {
+      if (!Object.prototype.hasOwnProperty.call(modules, 'network')) {
+        modules.network = modules.net;
+      }
+      delete modules.net;
+    }
+    normalized.modules = modules;
+  }
+
+  return normalized;
+}
+
+// ---------------------------------------------------------------------------
+// Schema definition
+// ---------------------------------------------------------------------------
+
+/**
+ * Config field descriptors.
+ *
+ * Each leaf field has:
+ *   type     — "string" | "number" | "boolean" | "enum"
+ *   default  — default value (or a function returning it when mode-dependent)
+ *   values   — (enum only) array of valid values
+ *   validate — optional extra validation function; return string on error
+ */
+const SCHEMA = {
+  identity: {
+    name:       { type: 'string', default: 'AuraJS Game' },
+    version:    { type: 'string', default: '0.1.0', validate: semverLike },
+    executable: { type: 'string', default: 'game', validate: safeExecutableName },
+    icon:       { type: 'string', default: null, validate: relativeAssetLikePath },
+  },
+  window: {
+    title:      { type: 'string',  default: 'AuraJS Game' },
+    width:      { type: 'number',  default: 800,  validate: positiveInteger },
+    height:     { type: 'number',  default: 600,  validate: positiveInteger },
+    resizable:  { type: 'boolean', default: true },
+    fullscreen: { type: 'boolean', default: false },
+    vsync:      { type: 'boolean', default: true },
+    hidpi:      { type: 'boolean', default: true },
+  },
+  build: {
+    entry:     { type: 'string',  default: 'src/main.js' },
+    outDir:    { type: 'string',  default: 'build' },
+    assetDir:  { type: 'string',  default: 'assets' },
+    assetMode: { type: 'enum',    default: 'embed', values: ['embed', 'sibling'] },
+    minify:    { type: 'boolean', default: (mode) => mode !== 'dev' },
+    sourcemap: { type: 'boolean', default: (mode) => mode === 'dev' },
+  },
+  modules: {
+    physics:     { type: 'boolean', default: false },
+    network:     { type: 'boolean', default: false },
+    multiplayer: { type: 'boolean', default: false },
+    steam:       { type: 'boolean', default: false },
+  },
+};
+
+// ---------------------------------------------------------------------------
+// Validation helpers
+// ---------------------------------------------------------------------------
+
+function positiveInteger(value, path) {
+  if (!Number.isInteger(value) || value < 1) {
+    return `${path} must be a positive integer, got: ${JSON.stringify(value)}`;
+  }
+  return null;
+}
+
+function semverLike(value, path) {
+  const normalized = String(value || '').trim();
+  const semverPattern = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z-.]+)?(?:\+[0-9A-Za-z-.]+)?$/;
+  if (!semverPattern.test(normalized)) {
+    return `${path} must be a semantic version (for example 1.2.3), got: ${JSON.stringify(value)}`;
+  }
+  return null;
+}
+
+function safeExecutableName(value, path) {
+  const normalized = String(value || '').trim();
+  if (normalized.length === 0) {
+    return `${path} must be a non-empty string`;
+  }
+  if (/[/\\]/.test(normalized)) {
+    return `${path} must not include path separators, got: ${JSON.stringify(value)}`;
+  }
+  if (!/[A-Za-z0-9]/.test(normalized)) {
+    return `${path} must include at least one alphanumeric character, got: ${JSON.stringify(value)}`;
+  }
+  return null;
+}
+
+function relativeAssetLikePath(value, path) {
+  const normalized = String(value || '').trim();
+  if (normalized.length === 0) {
+    return `${path} must be a non-empty string`;
+  }
+  if (/^(?:[A-Za-z]+:)?[/\\]{1,2}/.test(normalized)) {
+    return `${path} must be a project-relative asset path, got: ${JSON.stringify(value)}`;
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Core validation + defaults
+// ---------------------------------------------------------------------------
+
+/**
+ * Validate a raw config object against the schema and merge with defaults.
+ *
+ * @param {object} raw   — User-supplied config (may be partial or empty).
+ * @param {object} opts  — { mode: "dev" | "build" | "run" }
+ * @returns {object} Deeply-frozen config object.
+ * @throws {ConfigError} On validation failure.
+ */
+export function validateConfig(raw, opts = {}) {
+  const mode = opts.mode || 'build';
+  const errors = [];
+  const result = {};
+
+  if (raw !== null && raw !== undefined && (typeof raw !== 'object' || Array.isArray(raw))) {
+    throw new ConfigError('Config must be an object (or null/undefined for defaults).');
+  }
+
+  const source = normalizeLegacyConfig(raw || {});
+  const windowTitleExplicitlyConfigured = Boolean(
+    source?.window
+    && typeof source.window === 'object'
+    && !Array.isArray(source.window)
+    && Object.prototype.hasOwnProperty.call(source.window, 'title'),
+  );
+
+  // Reject unknown top-level keys.
+  for (const key of Object.keys(source)) {
+    if (!SCHEMA[key]) {
+      errors.push(`Unknown top-level config key: "${key}".`);
+    }
+  }
+
+  for (const [section, fields] of Object.entries(SCHEMA)) {
+    const userSection = source[section];
+
+    if (userSection !== undefined && userSection !== null) {
+      if (typeof userSection !== 'object' || Array.isArray(userSection)) {
+        errors.push(`"${section}" must be an object.`);
+        result[section] = buildSectionDefaults(section, fields, mode);
+        continue;
+      }
+      // Reject unknown keys inside section.
+      for (const key of Object.keys(userSection)) {
+        if (!fields[key]) {
+          errors.push(`Unknown config key: "${section}.${key}".`);
+        }
+      }
+    }
+
+    result[section] = {};
+
+    for (const [field, descriptor] of Object.entries(fields)) {
+      const path = `${section}.${field}`;
+      const userValue = userSection?.[field];
+
+      if (userValue === undefined || userValue === null) {
+        result[section][field] = resolveDefault(descriptor.default, mode);
+        continue;
+      }
+
+      // Type check.
+      const typeError = checkType(descriptor, userValue, path);
+      if (typeError) {
+        errors.push(typeError);
+        result[section][field] = resolveDefault(descriptor.default, mode);
+        continue;
+      }
+
+      // Extra validation.
+      if (descriptor.validate) {
+        const extra = descriptor.validate(userValue, path);
+        if (extra) {
+          errors.push(extra);
+          result[section][field] = resolveDefault(descriptor.default, mode);
+          continue;
+        }
+      }
+
+      result[section][field] = userValue;
+    }
+  }
+
+  if (errors.length > 0) {
+    throw new ConfigError(
+      `Invalid aura.config:\n${errors.map((e) => `  - ${e}`).join('\n')}`,
+      { errors },
+    );
+  }
+
+  if (!windowTitleExplicitlyConfigured && typeof result.identity?.name === 'string') {
+    result.window.title = result.identity.name;
+  }
+
+  return deepFreeze(result);
+}
+
+function resolveDefault(def, mode) {
+  return typeof def === 'function' ? def(mode) : def;
+}
+
+function buildSectionDefaults(section, fields, mode) {
+  const out = {};
+  for (const [field, descriptor] of Object.entries(fields)) {
+    out[field] = resolveDefault(descriptor.default, mode);
+  }
+  return out;
+}
+
+function checkType(descriptor, value, path) {
+  switch (descriptor.type) {
+    case 'string':
+      if (typeof value !== 'string') {
+        return `${path} must be a string, got: ${JSON.stringify(value)}`;
+      }
+      return null;
+
+    case 'number':
+      if (typeof value !== 'number' || !Number.isFinite(value)) {
+        return `${path} must be a finite number, got: ${JSON.stringify(value)}`;
+      }
+      return null;
+
+    case 'boolean':
+      if (typeof value !== 'boolean') {
+        return `${path} must be a boolean, got: ${JSON.stringify(value)}`;
+      }
+      return null;
+
+    case 'enum':
+      if (!descriptor.values.includes(value)) {
+        return `${path} must be one of [${descriptor.values.map((v) => `"${v}"`).join(', ')}], got: ${JSON.stringify(value)}`;
+      }
+      return null;
+
+    default:
+      return `${path}: unknown schema type "${descriptor.type}".`;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Deep freeze
+// ---------------------------------------------------------------------------
+
+function deepFreeze(obj) {
+  Object.freeze(obj);
+  for (const value of Object.values(obj)) {
+    if (value !== null && typeof value === 'object' && !Object.isFrozen(value)) {
+      deepFreeze(value);
+    }
+  }
+  return obj;
+}
+
+// ---------------------------------------------------------------------------
+// File loading
+// ---------------------------------------------------------------------------
+
+const CONFIG_NAMES = ['aura.config.js', 'aura.config.mjs', 'aura.config.json'];
+
+/**
+ * Load an aura config from the project root.
+ *
+ * Searches for aura.config.js, aura.config.mjs, aura.config.json in order.
+ * Falls back to all defaults when no file is found.
+ *
+ * @param {object} opts
+ * @param {string} opts.projectRoot — Absolute path to project root.
+ * @param {string} opts.mode        — "dev" | "build" | "run".
+ * @returns {Promise<object>} Deeply-frozen config object.
+ * @throws {ConfigError} On invalid config.
+ */
+export async function loadConfig(opts = {}) {
+  const projectRoot = resolve(opts.projectRoot || process.cwd());
+  const mode = opts.mode || 'build';
+
+  for (const name of CONFIG_NAMES) {
+    const filePath = join(projectRoot, name);
+    if (!existsSync(filePath)) continue;
+
+    let raw;
+
+    if (name.endsWith('.json')) {
+      try {
+        const text = readFileSync(filePath, 'utf8');
+        raw = JSON.parse(text);
+      } catch (err) {
+        throw new ConfigError(`Failed to parse ${name}: ${err.message}`, { file: filePath });
+      }
+    } else {
+      // .js or .mjs — use dynamic import.
+      try {
+        const fileUrl = pathToFileURL(filePath).href;
+        const mod = await import(fileUrl);
+        raw = mod.default !== undefined ? mod.default : mod;
+      } catch (err) {
+        throw new ConfigError(`Failed to load ${name}: ${err.message}`, { file: filePath });
+      }
+    }
+
+    return validateConfig(raw, { mode });
+  }
+
+  // No config file found — return defaults.
+  return validateConfig({}, { mode });
+}
+
+/**
+ * Synchronous variant for .json-only loading (or defaults).
+ * Falls back to async loadConfig if a .js/.mjs file is found.
+ *
+ * @param {object} opts
+ * @returns {object|null} Frozen config, or null if async loading is required.
+ */
+export function loadConfigSync(opts = {}) {
+  const projectRoot = resolve(opts.projectRoot || process.cwd());
+  const mode = opts.mode || 'build';
+
+  for (const name of CONFIG_NAMES) {
+    const filePath = join(projectRoot, name);
+    if (!existsSync(filePath)) continue;
+
+    if (!name.endsWith('.json')) {
+      // Cannot synchronously load .js/.mjs — caller must use async loadConfig.
+      return null;
+    }
+
+    let raw;
+    try {
+      const text = readFileSync(filePath, 'utf8');
+      raw = JSON.parse(text);
+    } catch (err) {
+      throw new ConfigError(`Failed to parse ${name}: ${err.message}`, { file: filePath });
+    }
+
+    return validateConfig(raw, { mode });
+  }
+
+  return validateConfig({}, { mode });
+}