@auraindustry/aurajs 0.0.7 → 0.1.0

package/src/project-importer.mjs

@@ -0,0 +1,620 @@
+import {
+  cpSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  statSync,
+  writeFileSync,
+} from 'node:fs';
+import { basename, dirname, extname, join, relative, resolve } from 'node:path';
+
+import { scaffoldGame } from './scaffold.mjs';
+
+const SOURCE_CODE_EXTENSIONS = new Set(['.js', '.mjs', '.cjs', '.jsx', '.ts', '.tsx']);
+const SCENE_EXTENSIONS = new Set(['.glb', '.gltf']);
+const SKIP_DIR_NAMES = new Set([
+  '.aura',
+  '.git',
+  '.idea',
+  '.next',
+  '.turbo',
+  '.vscode',
+  'aurajs',
+  'build',
+  'coverage',
+  'dist',
+  'node_modules',
+  'out',
+  'tasks',
+]);
+const DEFAULT_UNSUPPORTED_FEATURES = Object.freeze([
+  {
+    code: 'manual_review_required',
+    message:
+      'Gameplay logic, DOM UI, runtime-generated geometry, physics integrations, and bespoke app flow still require manual AuraJS authoring.',
+  },
+  {
+    code: 'custom_shaders_not_migrated',
+    message:
+      'Custom GLSL, node-material graphs, and renderer/plugin mutations are not converted automatically in this MVP.',
+  },
+]);
+
+export function parseFromArgs(args) {
+  const parsed = {
+    sourcePath: null,
+    sourceType: null,
+    outputPath: null,
+    projectName: null,
+    scenePath: null,
+    skipInstall: false,
+  };
+
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (arg === '--source') {
+      parsed.sourceType = readRequiredOptionValue(args, i, '--source').toLowerCase();
+      i += 1;
+      continue;
+    }
+    if (arg.startsWith('--source=')) {
+      parsed.sourceType = arg.slice('--source='.length).toLowerCase();
+      continue;
+    }
+    if (arg === '--out') {
+      parsed.outputPath = readRequiredOptionValue(args, i, '--out');
+      i += 1;
+      continue;
+    }
+    if (arg.startsWith('--out=')) {
+      parsed.outputPath = arg.slice('--out='.length);
+      continue;
+    }
+    if (arg === '--name') {
+      parsed.projectName = readRequiredOptionValue(args, i, '--name');
+      i += 1;
+      continue;
+    }
+    if (arg.startsWith('--name=')) {
+      parsed.projectName = arg.slice('--name='.length);
+      continue;
+    }
+    if (arg === '--scene') {
+      parsed.scenePath = readRequiredOptionValue(args, i, '--scene');
+      i += 1;
+      continue;
+    }
+    if (arg.startsWith('--scene=')) {
+      parsed.scenePath = arg.slice('--scene='.length);
+      continue;
+    }
+    if (arg === '--skip-install' || arg === '--no-install') {
+      parsed.skipInstall = true;
+      continue;
+    }
+    if (arg.startsWith('--')) {
+      throw new Error(`Unknown option for from: ${arg}`);
+    }
+    if (parsed.sourcePath !== null) {
+      throw new Error('Unexpected extra argument for from. Usage: aura from <source-path> --source threejs [--out <path>] [--name <name>] [--scene <path>] [--skip-install]');
+    }
+    parsed.sourcePath = arg;
+  }
+
+  if (!parsed.sourcePath) {
+    throw new Error('Missing source path. Usage: aura from <source-path> --source threejs [--out <path>] [--name <name>] [--scene <path>] [--skip-install]');
+  }
+  if (!parsed.sourceType) {
+    throw new Error('Missing --source. Currently supported: threejs.');
+  }
+  if (parsed.sourceType !== 'threejs') {
+    throw new Error(`Unsupported --source "${parsed.sourceType}". Currently supported: threejs.`);
+  }
+
+  return parsed;
+}
+
+export function detectThreeJsProject(options = {}) {
+  const sourceRoot = resolve(options.sourceRoot || process.cwd());
+  const packageJsonPath = resolve(sourceRoot, 'package.json');
+  const packageJson = readJsonIfPresent(packageJsonPath);
+  const dependencyNames = collectDependencyNames(packageJson);
+  const sceneCandidates = collectSceneCandidates(sourceRoot);
+  const sourceSignals = collectSourceSignals(sourceRoot);
+  const usesThreeDependency = dependencyNames.some((name) => (
+    name === 'three' || name.startsWith('@react-three/')
+  ));
+  const usesPostprocessing = dependencyNames.some((name) => (
+    name === 'postprocessing' || name === 'three-stdlib' || name === '@react-three/postprocessing'
+  ));
+  const detected = usesThreeDependency || sourceSignals.length > 0;
+
+  return {
+    detected,
+    sourceRoot,
+    packageJsonPath: existsSync(packageJsonPath) ? packageJsonPath : null,
+    packageName: packageJson && typeof packageJson.name === 'string' ? packageJson.name : null,
+    dependencyNames,
+    sceneCandidates,
+    sourceSignals,
+    usesThreeDependency,
+    usesPostprocessing,
+  };
+}
+
+export function importThreeJsProject(options = {}) {
+  const sourceRoot = resolve(options.sourceRoot || process.cwd());
+  const detection = detectThreeJsProject({ sourceRoot });
+  if (!detection.detected) {
+    throw new Error(`Could not verify a Three.js project at ${sourceRoot}. Add a package.json dependency on "three" or import "three" from source files before retrying.`);
+  }
+
+  const requestedScene = normalizeOptionalPath(options.scenePath);
+  const selectedSceneSourcePath = selectSceneCandidate(detection.sceneCandidates, requestedScene);
+  const projectName = normalizeImportedProjectName(
+    options.projectName
+    || detection.packageName
+    || basename(sourceRoot),
+  );
+  const outputRoot = resolve(options.outputPath || join(sourceRoot, 'aurajs', projectName));
+
+  scaffoldGame({
+    name: projectName,
+    dest: outputRoot,
+    template: 'blank',
+  });
+
+  const sceneCopy = copySelectedSceneIntoProject({
+    sourceRoot,
+    outputRoot,
+    selectedSceneSourcePath,
+  });
+  const report = buildImportReport({
+    detection,
+    outputRoot,
+    projectName,
+    requestedScene,
+    sceneCopy,
+  });
+
+  writeGeneratedBootstrap(outputRoot, report);
+  writeCapabilitiesDeclaration(outputRoot, report);
+
+  const reportPath = resolve(outputRoot, 'migration-report.json');
+  writeFileSync(reportPath, `${JSON.stringify(report, null, 2)}\n`, 'utf8');
+
+  return {
+    outputRoot,
+    projectName,
+    report,
+    reportPath,
+  };
+}
+
+function readRequiredOptionValue(args, index, flag) {
+  const value = args[index + 1];
+  if (!value || value.startsWith('--')) {
+    throw new Error(`Missing value for ${flag}.`);
+  }
+  return value;
+}
+
+function normalizeOptionalPath(value) {
+  if (typeof value !== 'string') return null;
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : null;
+}
+
+function normalizeImportedProjectName(value) {
+  const normalized = String(value || '')
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9_-]+/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/^[-_]+|[-_]+$/g, '');
+  return normalized || 'imported-threejs-project';
+}
+
+function readJsonIfPresent(filePath) {
+  if (!existsSync(filePath)) return null;
+  try {
+    return JSON.parse(readFileSync(filePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function collectDependencyNames(packageJson) {
+  if (!packageJson || typeof packageJson !== 'object') return [];
+  const names = new Set();
+  for (const key of ['dependencies', 'devDependencies', 'peerDependencies']) {
+    const deps = packageJson[key];
+    if (!deps || typeof deps !== 'object' || Array.isArray(deps)) continue;
+    for (const name of Object.keys(deps)) {
+      names.add(String(name));
+    }
+  }
+  return [...names].sort((a, b) => a.localeCompare(b));
+}
+
+function collectSceneCandidates(sourceRoot) {
+  const files = collectFiles(sourceRoot, {
+    shouldIncludeFile(filePath) {
+      return SCENE_EXTENSIONS.has(extname(filePath).toLowerCase());
+    },
+  });
+
+  return files
+    .map((filePath) => ({
+      sourcePath: filePath,
+      relativePath: toPosix(relative(sourceRoot, filePath)),
+      extension: extname(filePath).toLowerCase(),
+    }))
+    .sort((a, b) => {
+      const extScore = sceneExtensionScore(a.extension) - sceneExtensionScore(b.extension);
+      if (extScore !== 0) return extScore;
+      return a.relativePath.localeCompare(b.relativePath);
+    });
+}
+
+function sceneExtensionScore(extension) {
+  if (extension === '.glb') return 0;
+  if (extension === '.gltf') return 1;
+  return 10;
+}
+
+function collectSourceSignals(sourceRoot) {
+  const files = collectFiles(sourceRoot, {
+    shouldIncludeFile(filePath) {
+      return SOURCE_CODE_EXTENSIONS.has(extname(filePath).toLowerCase());
+    },
+    maxFiles: 240,
+  });
+
+  const results = [];
+  for (const filePath of files) {
+    let content = '';
+    try {
+      content = readFileSync(filePath, 'utf8');
+    } catch {
+      continue;
+    }
+    if (
+      !/['"]three['"]|@react-three\/(fiber|drei|postprocessing)/.test(content)
+      && !/OrbitControls|EffectComposer|WebGLRenderer|Scene\(/.test(content)
+    ) {
+      continue;
+    }
+    results.push({
+      file: toPosix(relative(sourceRoot, filePath)),
+      reason: 'threejs_source_signal_detected',
+    });
+    if (results.length >= 24) break;
+  }
+  return results;
+}
+
+function collectFiles(rootPath, options = {}) {
+  const output = [];
+  const maxFiles = Number.isInteger(options.maxFiles) && options.maxFiles > 0
+    ? options.maxFiles
+    : Number.POSITIVE_INFINITY;
+  walk(rootPath);
+  return output;
+
+  function walk(dirPath) {
+    if (output.length >= maxFiles) return;
+    const names = safeReadDir(dirPath);
+    for (const name of names) {
+      if (output.length >= maxFiles) return;
+      const fullPath = resolve(dirPath, name);
+      let stat = null;
+      try {
+        stat = statSync(fullPath);
+      } catch {
+        continue;
+      }
+      if (stat.isDirectory()) {
+        if (SKIP_DIR_NAMES.has(name)) continue;
+        walk(fullPath);
+        continue;
+      }
+      if (typeof options.shouldIncludeFile === 'function' && !options.shouldIncludeFile(fullPath)) {
+        continue;
+      }
+      output.push(fullPath);
+    }
+  }
+}
+
+function safeReadDir(dirPath) {
+  try {
+    return readdirSync(dirPath).sort((a, b) => a.localeCompare(b));
+  } catch {
+    return [];
+  }
+}
+
+function selectSceneCandidate(sceneCandidates, requestedScene) {
+  if (requestedScene) {
+    const normalizedRequested = toPosix(requestedScene.replace(/^\.?\//, ''));
+    const exact = sceneCandidates.find((entry) => entry.relativePath === normalizedRequested);
+    if (!exact) {
+      throw new Error(`Requested --scene "${requestedScene}" was not found under the source project.`);
+    }
+    return exact.sourcePath;
+  }
+  return sceneCandidates.length > 0 ? sceneCandidates[0].sourcePath : null;
+}
+
+function copySelectedSceneIntoProject({ sourceRoot, outputRoot, selectedSceneSourcePath }) {
+  if (!selectedSceneSourcePath) {
+    return {
+      sourceScenePath: null,
+      outputScenePath: null,
+      copiedRoots: [],
+    };
+  }
+
+  const extension = extname(selectedSceneSourcePath).toLowerCase();
+  const importedRoot = resolve(outputRoot, 'assets', 'imported');
+  mkdirSync(importedRoot, { recursive: true });
+
+  if (extension === '.glb') {
+    const targetPath = resolve(importedRoot, basename(selectedSceneSourcePath));
+    cpSync(selectedSceneSourcePath, targetPath);
+    return {
+      sourceScenePath: toPosix(relative(sourceRoot, selectedSceneSourcePath)),
+      outputScenePath: toPosix(relative(outputRoot, targetPath)),
+      copiedRoots: [toPosix(relative(outputRoot, targetPath))],
+    };
+  }
+
+  const sourceDir = dirname(selectedSceneSourcePath);
+  const dirLabel = normalizeImportedProjectName(basename(sourceDir) || 'scene-assets');
+  const targetDir = resolve(importedRoot, dirLabel);
+  cpSync(sourceDir, targetDir, { recursive: true });
+  const targetScenePath = resolve(targetDir, basename(selectedSceneSourcePath));
+  return {
+    sourceScenePath: toPosix(relative(sourceRoot, selectedSceneSourcePath)),
+    outputScenePath: toPosix(relative(outputRoot, targetScenePath)),
+    copiedRoots: [toPosix(relative(outputRoot, targetDir))],
+  };
+}
+
+function buildImportReport({ detection, outputRoot, projectName, requestedScene, sceneCopy }) {
+  const unsupportedFeatures = [...DEFAULT_UNSUPPORTED_FEATURES];
+  if (detection.dependencyNames.includes('@react-three/fiber')) {
+    unsupportedFeatures.push({
+      code: 'react_three_fiber_manual_rewrite_required',
+      message: 'React Three Fiber components are not migrated automatically; convert them into authored AuraJS runtime modules manually.',
+    });
+  }
+  if (detection.usesPostprocessing) {
+    unsupportedFeatures.push({
+      code: 'postprocessing_manual_rewrite_required',
+      message: 'EffectComposer and postprocessing stacks require a manual AuraJS draw3d/postfx rewrite.',
+    });
+  }
+  if (!sceneCopy.outputScenePath) {
+    unsupportedFeatures.push({
+      code: 'scene_export_required',
+      message: 'No glTF/GLB scene was discovered. Export a scene asset from the Three.js project and rerun the importer with --scene if needed.',
+    });
+  }
+
+  return {
+    schema: 'aurajs.threejs-import-report.v1',
+    sourceType: 'threejs',
+    projectName,
+    sourceRoot: detection.sourceRoot,
+    outputRoot,
+    detection: {
+      detected: detection.detected,
+      packageJsonPath: detection.packageJsonPath,
+      dependencyNames: detection.dependencyNames,
+      usesThreeDependency: detection.usesThreeDependency,
+      sourceSignals: detection.sourceSignals,
+    },
+    sceneImport: {
+      requestedScene,
+      candidates: detection.sceneCandidates.map((entry) => entry.relativePath),
+      selectedSourceScene: sceneCopy.sourceScenePath,
+      outputScenePath: sceneCopy.outputScenePath,
+      copiedRoots: sceneCopy.copiedRoots,
+      reasonCode: sceneCopy.outputScenePath
+        ? 'threejs_scene_selected'
+        : 'threejs_scene_missing',
+    },
+    unsupportedFeatures,
+    nextSteps: sceneCopy.outputScenePath
+      ? [
+        'Run `npm install` inside the generated AuraJS project if dependencies were not installed.',
+        'Run `npm run dev` and verify the imported scene loads through the generated bootstrap.',
+        'Rewrite gameplay, UI, and any renderer-specific logic using AuraJS runtime surfaces.',
+      ]
+      : [
+        'Export a .glb or .gltf scene from the source project.',
+        'Rerun the importer with `--scene <relative-path>` once the scene asset exists.',
+        'Port gameplay and UI manually after the scene path is stable.',
+      ],
+  };
+}
+
+function writeGeneratedBootstrap(outputRoot, report) {
+  const scenePath = report.sceneImport.outputScenePath;
+  const mainSource = buildGeneratedMainSource({
+    projectName: report.projectName,
+    scenePath,
+  });
+  writeFileSync(resolve(outputRoot, 'src', 'main.js'), mainSource, 'utf8');
+}
+
+function writeCapabilitiesDeclaration(outputRoot, report) {
+  const capabilitiesPath = resolve(outputRoot, 'aura.capabilities.json');
+  const capabilities = readJsonIfPresent(capabilitiesPath) || {};
+  const requiredApis = new Set(Array.isArray(capabilities.requiredApis) ? capabilities.requiredApis : []);
+  for (const apiName of [
+    'aura.draw2d.clear',
+    'aura.draw2d.text',
+    'aura.draw3d.clear3d',
+    'aura.camera3d.lookAt',
+    'aura.camera3d.perspective',
+    'aura.camera3d.setPosition',
+    'aura.light.ambient',
+    'aura.light.directional',
+    'aura.rgb',
+    'aura.rgba',
+  ]) {
+    requiredApis.add(apiName);
+  }
+  if (report.sceneImport.outputScenePath) {
+    for (const apiName of [
+      'aura.scene3d.getImportedScene',
+      'aura.scene3d.loadGltfScene',
+      'aura.scene3d.submitRenderBindings',
+      'aura.scene3d.updateClips',
+    ]) {
+      requiredApis.add(apiName);
+    }
+  }
+
+  capabilities.schema = capabilities.schema || 'aurajs.create-capabilities.v1';
+  capabilities.template = capabilities.template || 'blank';
+  capabilities.summary = 'Generated from a Three.js project by the AuraJS importer.';
+  capabilities.requiredApis = [...requiredApis].sort((a, b) => a.localeCompare(b));
+  capabilities.notes = [
+    'Generated by `aura from --source threejs`.',
+    'Keep this file aligned with generated bootstrap changes and later manual migration work.',
+  ];
+
+  writeFileSync(capabilitiesPath, `${JSON.stringify(capabilities, null, 2)}\n`, 'utf8');
+}
+
+function buildGeneratedMainSource({ projectName, scenePath }) {
+  const sceneCandidates = scenePath ? [scenePath] : [];
+  return `// ${projectName} — generated by \`aura from --source threejs\`
+
+const IMPORTED_SCENE_CANDIDATES = Object.freeze(${JSON.stringify(sceneCandidates, null, 2)});
+
+const state = {
+  loadedScenePath: null,
+  importId: 0,
+  importSummary: '',
+  error: '',
+};
+
+function hasMethod(obj, method) {
+  return Boolean(obj) && typeof obj[method] === 'function';
+}
+
+function rgba(r, g, b, a = 1) {
+  return { r, g, b, a };
+}
+
+function tryLoadImportedScene() {
+  if (!hasMethod(aura.scene3d, 'loadGltfScene')) {
+    state.error = 'aura.scene3d.loadGltfScene is unavailable in this runtime.';
+    return false;
+  }
+
+  for (const candidate of IMPORTED_SCENE_CANDIDATES) {
+    try {
+      const loaded = aura.scene3d.loadGltfScene(candidate, {
+        bindRenderNodes: true,
+        visible: true,
+        cull: false,
+      });
+      const record = Number.isInteger(loaded)
+        ? { importId: loaded }
+        : loaded;
+      const importId = Number(record && record.importId ? record.importId : loaded);
+      if (!Number.isInteger(importId) || importId <= 0) {
+        continue;
+      }
+      const summary = hasMethod(aura.scene3d, 'getImportedScene')
+        ? aura.scene3d.getImportedScene(importId)
+        : null;
+      state.loadedScenePath = candidate;
+      state.importId = importId;
+      state.importSummary = summary && typeof summary === 'object'
+        ? \`\${Number(summary.nodeCount || 0)} nodes / \${Number(summary.primitiveCount || 0)} prims / \${Number(summary.materialCount || 0)} mats\`
+        : 'scene import loaded';
+      return true;
+    } catch (error) {
+      state.error = String(error && error.message ? error.message : error);
+    }
+  }
+
+  if (!state.error && IMPORTED_SCENE_CANDIDATES.length === 0) {
+    state.error = 'No glTF/GLB scene was selected during import.';
+  }
+  return false;
+}
+
+aura.setup = function () {
+  if (hasMethod(aura.camera3d, 'perspective')) {
+    aura.camera3d.perspective(58, 0.1, 120);
+  }
+  if (hasMethod(aura.camera3d, 'setPosition')) {
+    aura.camera3d.setPosition(0, 2.8, 6.8);
+  }
+  if (hasMethod(aura.camera3d, 'lookAt')) {
+    aura.camera3d.lookAt(0, 1.1, 0);
+  }
+  if (hasMethod(aura.light, 'ambient')) {
+    aura.light.ambient(rgba(1, 1, 1, 1), 0.32);
+  }
+  if (hasMethod(aura.light, 'directional')) {
+    aura.light.directional({ x: -0.55, y: -1, z: -0.4 }, rgba(1, 0.97, 0.92, 1), 1.1);
+  }
+
+  tryLoadImportedScene();
+};
+
+aura.update = function (dt) {
+  if (hasMethod(aura.scene3d, 'updateClips')) {
+    aura.scene3d.updateClips(Number.isFinite(dt) ? dt : 0);
+  }
+};
+
+aura.draw = function () {
+  if (hasMethod(aura.draw3d, 'clear3d')) {
+    aura.draw3d.clear3d(rgba(0.035, 0.04, 0.055, 1));
+  } else if (hasMethod(aura.draw2d, 'clear')) {
+    aura.draw2d.clear(rgba(0.035, 0.04, 0.055, 1));
+  }
+
+  if (state.importId > 0 && hasMethod(aura.scene3d, 'submitRenderBindings')) {
+    aura.scene3d.submitRenderBindings();
+  }
+
+  if (!hasMethod(aura.draw2d, 'text') || typeof aura.rgb !== 'function') {
+    return;
+  }
+
+  aura.draw2d.text('${projectName} — imported from Three.js', 24, 24, {
+    size: 20,
+    color: aura.rgb(0.96, 0.97, 1),
+  });
+  aura.draw2d.text(
+    state.loadedScenePath
+      ? \`scene: \${state.loadedScenePath}\`
+      : 'scene: none detected',
+    24,
+    52,
+    { size: 14, color: aura.rgb(0.82, 0.9, 0.98) },
+  );
+  aura.draw2d.text(
+    state.importSummary || state.error || 'manual gameplay migration still required',
+    24,
+    74,
+    { size: 14, color: aura.rgb(0.88, 0.9, 0.84) },
+  );
+};\n`;
+}
+
+function toPosix(value) {
+  return String(value || '').split('\\\\').join('/');
+}

package/src/project-registry.mjs

@@ -0,0 +1,24 @@
+export {
+  CANONICAL_PREFAB_ROLES,
+  PROJECT_CHECK_SCHEMA,
+  PROJECT_CONTINUITY_SCHEMA,
+  PROJECT_EXPLAIN_SCHEMA,
+  PROJECT_REGISTRY_RELATIVE_PATH,
+  PROJECT_REGISTRY_SCHEMA,
+  SCENE_REGISTRY_RELATIVE_PATH,
+  assertAuraProjectRoot,
+  buildStarterRegistryEntries,
+  checkProject,
+  createScaffoldProjectRegistryModel,
+  createStarterProjectRegistry,
+  explainProject,
+  getProjectRegistryRelativePath,
+  getSceneRegistryRelativePath,
+  inferPrefabRole,
+  isSelfWiringMakeKind,
+  normalizePrefabRole,
+  registerGeneratedProjectFiles,
+  runProjectCheck,
+  runProjectExplain,
+  writeProjectRegistryFiles,
+} from './authored-project.mjs';