@helix3/helix-cli 0.1.14-helix3.176 → 0.1.14-helix3.178

package/bridge-plugins/helix.bridge.unreal/bin/unreal-skeletal-mesh-extract.js

@@ -0,0 +1,632 @@
+#!/usr/bin/env node
+'use strict';
+
+const { spawn, spawnSync } = require('node:child_process');
+const { createHash } = require('node:crypto');
+const {
+  closeSync,
+  existsSync,
+  lstatSync,
+  openSync,
+  readFileSync,
+  readSync,
+  readdirSync,
+  realpathSync,
+  statSync,
+} = require('node:fs');
+const { basename, extname, isAbsolute, join, relative, resolve, sep } = require('node:path');
+
+const REQUEST_SCHEMA = 'helix.bridge-plugin-request/1';
+const PROFILE_SCHEMA = 'helix.bridge.unreal-asset/1';
+const PROFILE_SET_SCHEMA = 'helix.bridge.unreal-asset-set/1';
+const CAPABILITY = 'unreal.project.extract';
+const MAX_PROFILE_BYTES = 64 * 1024;
+const MAX_PROJECT_ENTRIES = 100_000;
+const LOG_TAIL_BYTES = 16 * 1024;
+const FBX_HEADER_BYTES = 1024;
+const FBX_BINARY_HEADER = Buffer.from('Kaydara FBX Binary  \0\x1a\0', 'binary');
+const FBX_ASCII_HEADER = /^;\s+FBX\s+\d+\.\d+\.\d+\s+project\s+file(?:\r?\n|$)/;
+const MATERIAL_SIDECAR_SCHEMA = 'helix.bridge.unreal-material-sidecar/1';
+const MAX_MATERIAL_SIDECAR_BYTES = 16 * 1024 * 1024;
+const PNG_HEADER = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+const SHA256 = /^[a-f0-9]{64}$/;
+const TEXTURE_RELATIVE_PATH = /^textures\/([a-f0-9]{64})\.png$/;
+const SLUG = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const WINDOWS_ABSOLUTE_PATH = /^(?:[a-zA-Z]:[\\/]|\\\\)/;
+const UNREAL_ASSET_PATH = /^\/[A-Za-z0-9_+]+\/(?:[A-Za-z0-9_+]+\/)*[A-Za-z0-9_+]+(?:\.[A-Za-z0-9_+]+)?$/;
+const WSL_BRIDGE_ENVIRONMENT = [
+  'HELIX_UNREAL_ASSET_PATH',
+  'HELIX_UNREAL_OUTPUT_FBX',
+  'HELIX_UNREAL_EXPORT_MORPH_TARGETS',
+  'HELIX_UNREAL_EXPORTS_JSON',
+];
+
+function fail(message) {
+  throw new Error(message);
+}
+
+function object(value, label) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    fail(`${label} must be an object`);
+  }
+  return value;
+}
+
+function nonEmptyString(value, label) {
+  if (typeof value !== 'string' || value.trim() === '') {
+    fail(`${label} must be a non-empty string`);
+  }
+  return value;
+}
+
+function exactKeys(value, expected, label) {
+  const actual = Object.keys(value).sort();
+  const allowed = [...expected].sort();
+  if (actual.length !== allowed.length || actual.some((key, index) => key !== allowed[index])) {
+    fail(`${label} must contain exactly: ${allowed.join(', ')}`);
+  }
+}
+
+function finiteNumber(value, label) {
+  if (typeof value !== 'number' || !Number.isFinite(value)) fail(`${label} must be a finite number`);
+  return value;
+}
+
+function portableUnrealPath(value, label) {
+  const path = nonEmptyString(value, label);
+  if (!UNREAL_ASSET_PATH.test(path) || path.includes('//') || path.includes('\\') || path.includes('..')) {
+    fail(`${label} must be a portable mounted Unreal asset path`);
+  }
+  return path;
+}
+
+function containedPath(root, candidate, label) {
+  const rel = relative(root, candidate);
+  if (rel === '' || rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel)) {
+    fail(`${label} escapes the reviewed output directory`);
+  }
+}
+
+function regularFile(path, label, maximumBytes) {
+  let info;
+  try {
+    info = lstatSync(path);
+  } catch (error) {
+    fail(`${label} is unavailable: ${error.message}`);
+  }
+  if (!info.isFile() || info.isSymbolicLink()) fail(`${label} must be a regular non-symlink file`);
+  if (maximumBytes !== undefined && info.size > maximumBytes) {
+    fail(`${label} exceeds the ${maximumBytes}-byte limit`);
+  }
+  return info;
+}
+
+function hashAndSize(path) {
+  const digest = createHash('sha256');
+  const buffer = Buffer.alloc(1024 * 1024);
+  const descriptor = openSync(path, 'r');
+  let sizeBytes = 0;
+  try {
+    while (true) {
+      const bytesRead = readSync(descriptor, buffer, 0, buffer.length, null);
+      if (bytesRead === 0) break;
+      digest.update(buffer.subarray(0, bytesRead));
+      sizeBytes += bytesRead;
+    }
+  } finally {
+    closeSync(descriptor);
+  }
+  return { sha256: digest.digest('hex'), sizeBytes };
+}
+
+function hasHeader(path, expected) {
+  const header = Buffer.alloc(expected.length);
+  const descriptor = openSync(path, 'r');
+  try {
+    return readSync(descriptor, header, 0, header.length, 0) === header.length && header.equals(expected);
+  } finally {
+    closeSync(descriptor);
+  }
+}
+
+function readJsonFile(path, label) {
+  let info;
+  try {
+    info = lstatSync(path);
+  } catch (error) {
+    fail(`${label} is unavailable: ${error.message}`);
+  }
+  if (!info.isFile() || info.isSymbolicLink()) {
+    fail(`${label} must be a regular non-symlink file`);
+  }
+  if (info.size > MAX_PROFILE_BYTES) {
+    fail(`${label} exceeds the ${MAX_PROFILE_BYTES}-byte limit`);
+  }
+  try {
+    return JSON.parse(readFileSync(path, 'utf8'));
+  } catch (error) {
+    fail(`${label} is not valid JSON: ${error.message}`);
+  }
+}
+
+function validateRequest(value) {
+  const request = object(value, 'Bridge request');
+  if (request.schemaVersion !== REQUEST_SCHEMA) {
+    fail(`Bridge request schemaVersion must be '${REQUEST_SCHEMA}'`);
+  }
+  if (request.capability !== CAPABILITY) {
+    fail(`Bridge request capability must be '${CAPABILITY}'`);
+  }
+  const source = object(request.source, 'Bridge request source');
+  if (source.sourceKind !== 'unreal.project') {
+    fail("Bridge request sourceKind must be 'unreal.project'");
+  }
+  const sourcePath = resolve(nonEmptyString(source.source, 'Bridge request source path'));
+  const outputDir = resolve(nonEmptyString(request.outputDir, 'Bridge request outputDir'));
+  const inputs = object(request.inputs, 'Bridge request inputs');
+  const assetInput = object(inputs.unrealAsset, "Bridge request input 'unrealAsset'");
+  const profilePath = resolve(nonEmptyString(assetInput.path, "Bridge request input 'unrealAsset'.path"));
+  return { sourcePath, outputDir, profilePath };
+}
+
+function validateAsset(value, label) {
+  const profile = object(value, label);
+  const slug = nonEmptyString(profile.slug, 'Unreal asset profile slug');
+  if (slug.length > 64 || !SLUG.test(slug)) {
+    fail('Unreal asset profile slug must be lowercase alphanumeric words separated by single hyphens');
+  }
+  const assetPath = nonEmptyString(profile.assetPath, 'Unreal asset profile assetPath');
+  if (!UNREAL_ASSET_PATH.test(assetPath) || assetPath.includes('//')) {
+    fail("Unreal asset profile assetPath must be a mounted virtual Unreal asset path such as '/Game/...' or '/PluginName/...'");
+  }
+  if (profile.exportMorphTargets !== undefined && typeof profile.exportMorphTargets !== 'boolean') {
+    fail('Unreal asset profile exportMorphTargets must be a boolean when provided');
+  }
+  return {
+    slug,
+    assetPath,
+    exportMorphTargets: profile.exportMorphTargets ?? true,
+  };
+}
+
+function validateProfile(value) {
+  const profile = object(value, 'Unreal asset profile');
+  if (profile.schemaVersion === PROFILE_SCHEMA) return [validateAsset(profile, 'Unreal asset profile')];
+  if (profile.schemaVersion !== PROFILE_SET_SCHEMA) {
+    fail(`Unreal asset profile schemaVersion must be '${PROFILE_SCHEMA}' or '${PROFILE_SET_SCHEMA}'`);
+  }
+  if (!Array.isArray(profile.assets) || profile.assets.length === 0 || profile.assets.length > 64) {
+    fail('Unreal asset-set profile assets must contain between 1 and 64 entries');
+  }
+  const assets = profile.assets.map((asset, index) => validateAsset(asset, `Unreal asset-set profile assets[${index}]`));
+  if (new Set(assets.map((asset) => asset.slug)).size !== assets.length) {
+    fail('Unreal asset-set profile slugs must be unique');
+  }
+  return assets;
+}
+
+function findProject(sourcePath) {
+  let root;
+  try {
+    root = lstatSync(sourcePath);
+  } catch (error) {
+    fail(`Unreal project snapshot is unavailable: ${error.message}`);
+  }
+  if (!root.isDirectory() || root.isSymbolicLink()) {
+    fail('Unreal project snapshot must be a regular directory');
+  }
+
+  const projects = [];
+  const pending = [sourcePath];
+  let entryCount = 0;
+  while (pending.length > 0) {
+    const directory = pending.pop();
+    const entries = readdirSync(directory, { withFileTypes: true });
+    for (const entry of entries) {
+      entryCount += 1;
+      if (entryCount > MAX_PROJECT_ENTRIES) {
+        fail(`Unreal project snapshot exceeds the ${MAX_PROJECT_ENTRIES}-entry adapter limit`);
+      }
+      const path = join(directory, entry.name);
+      if (entry.isSymbolicLink()) fail(`Unreal project snapshot contains a symlink: ${path}`);
+      if (entry.isDirectory()) {
+        pending.push(path);
+      } else if (entry.isFile() && extname(entry.name).toLowerCase() === '.uproject') {
+        projects.push(path);
+      }
+    }
+  }
+  if (projects.length !== 1) {
+    fail(`Unreal project snapshot must contain exactly one .uproject file; found ${projects.length}`);
+  }
+  return projects[0];
+}
+
+function runningInWsl() {
+  if (process.platform !== 'linux') return false;
+  if (process.env.WSL_DISTRO_NAME || process.env.WSL_INTEROP) return true;
+  try {
+    return /microsoft/i.test(readFileSync('/proc/sys/kernel/osrelease', 'utf8'));
+  } catch {
+    return false;
+  }
+}
+
+function wslPath(mode, path) {
+  const result = spawnSync('wslpath', [mode, path], {
+    encoding: 'utf8',
+    shell: false,
+    windowsHide: true,
+  });
+  if (result.error || result.status !== 0) {
+    const reason = result.error?.message || String(result.stderr || '').trim() || `exit ${result.status}`;
+    fail(`Unable to translate WSL path '${path}': ${reason}`);
+  }
+  return result.stdout.trim();
+}
+
+function editorInvocationPaths(editor, project, script, outputs) {
+  const wsl = runningInWsl();
+  if (!wsl) return { editor, project, script, outputs, wsl };
+  return {
+    editor: WINDOWS_ABSOLUTE_PATH.test(editor) ? wslPath('-u', editor) : editor,
+    project: wslPath('-w', project),
+    script: wslPath('-w', script),
+    outputs: outputs.map((output) => wslPath('-w', output)),
+    wsl,
+  };
+}
+
+function editorEnvironment(environment, wsl) {
+  if (!wsl) return environment;
+  const inherited = String(environment.WSLENV || '')
+    .split(':')
+    .filter(Boolean)
+    .filter((entry) => !WSL_BRIDGE_ENVIRONMENT.includes(entry.split('/')[0]));
+  return {
+    ...environment,
+    WSLENV: [...inherited, ...WSL_BRIDGE_ENVIRONMENT].join(':'),
+  };
+}
+
+function logTail() {
+  const chunks = [];
+  let size = 0;
+  return {
+    append(chunk) {
+      let next = Buffer.from(chunk);
+      if (next.length >= LOG_TAIL_BYTES) {
+        chunks.length = 0;
+        next = next.subarray(next.length - LOG_TAIL_BYTES);
+        chunks.push(next);
+        size = next.length;
+        return;
+      }
+      chunks.push(next);
+      size += next.length;
+      while (size > LOG_TAIL_BYTES) {
+        const excess = size - LOG_TAIL_BYTES;
+        const first = chunks[0];
+        if (first.length <= excess) {
+          chunks.shift();
+          size -= first.length;
+        } else {
+          chunks[0] = first.subarray(excess);
+          size -= excess;
+        }
+      }
+    },
+    text() {
+      return Buffer.concat(chunks, size).toString('utf8').trim();
+    },
+  };
+}
+
+async function runEditor(editor, args, environment) {
+  const stderr = logTail();
+  const stdout = logTail();
+  return new Promise((resolvePromise, rejectPromise) => {
+    const child = spawn(editor, args, {
+      env: environment,
+      shell: false,
+      stdio: ['ignore', 'pipe', 'pipe'],
+      windowsHide: true,
+    });
+    child.stdout.on('data', (chunk) => stdout.append(chunk));
+    child.stderr.on('data', (chunk) => stderr.append(chunk));
+    child.on('error', (error) => rejectPromise(new Error(`Unreal Editor failed to start: ${error.message}`)));
+    child.on('close', (code, signal) => {
+      resolvePromise({
+        code,
+        signal,
+        tail: [stdout.text(), stderr.text()].filter(Boolean).join('\n'),
+      });
+    });
+  });
+}
+
+function editorFailure(outcome) {
+  return `Unreal Editor failed${outcome.signal ? ` with signal ${outcome.signal}` : ` with exit ${outcome.code}`}` +
+    `${outcome.tail ? `: ${outcome.tail}` : ''}`;
+}
+
+function isKnownBenignPlatformValidationShutdown(outcome) {
+  if (outcome.signal || outcome.code !== 5) return false;
+  return /Running UnrealBuildTool:\s+dotnet\s+"[^"\r\n]*UnrealBuildTool\.dll"\s+-Mode=ValidatePlatforms\b[^\r\n]*\s-AllPlatforms(?:\s|$)/i.test(outcome.tail) &&
+    /Unable to find required SDK version ['"]MainVersion['"] for platform VisionOS\. Check your SDK\.json files/i.test(outcome.tail);
+}
+
+function validateFbxOutput(output) {
+  let exported;
+  try {
+    exported = lstatSync(output);
+  } catch (error) {
+    return `missing '${basename(output)}': ${error.message}`;
+  }
+  if (!exported.isFile() || exported.isSymbolicLink() || exported.size === 0) {
+    return `invalid or empty '${basename(output)}'`;
+  }
+
+  const header = Buffer.alloc(Math.min(FBX_HEADER_BYTES, exported.size));
+  let descriptor;
+  try {
+    descriptor = openSync(output, 'r');
+    const bytesRead = readSync(descriptor, header, 0, header.length, 0);
+    if (bytesRead !== header.length) return `could not read the complete header of '${basename(output)}'`;
+  } catch (error) {
+    return `could not read '${basename(output)}': ${error.message}`;
+  } finally {
+    if (descriptor !== undefined) closeSync(descriptor);
+  }
+
+  const binary = header.subarray(0, FBX_BINARY_HEADER.length).equals(FBX_BINARY_HEADER);
+  const ascii = FBX_ASCII_HEADER.test(header.toString('ascii'));
+  return binary || ascii ? null : `'${basename(output)}' is not a structurally valid FBX`;
+}
+
+function validateNumericDictionary(value, label) {
+  const dictionary = object(value, label);
+  for (const [name, number] of Object.entries(dictionary)) {
+    nonEmptyString(name, `${label} parameter name`);
+    finiteNumber(number, `${label}.${name}`);
+  }
+  return dictionary;
+}
+
+function validateVectorDictionary(value, label) {
+  const dictionary = object(value, label);
+  for (const [name, vectorValue] of Object.entries(dictionary)) {
+    nonEmptyString(name, `${label} parameter name`);
+    const vector = object(vectorValue, `${label}.${name}`);
+    exactKeys(vector, ['r', 'g', 'b', 'a'], `${label}.${name}`);
+    for (const channel of ['r', 'g', 'b', 'a']) finiteNumber(vector[channel], `${label}.${name}.${channel}`);
+  }
+  return dictionary;
+}
+
+function validateTextureBinding(value, outputRoot, label) {
+  const binding = object(value, label);
+  exactKeys(binding, ['sourceAssetPath', 'path', 'sha256', 'sizeBytes', 'colorSpace'], label);
+  portableUnrealPath(binding.sourceAssetPath, `${label}.sourceAssetPath`);
+  const relativePath = nonEmptyString(binding.path, `${label}.path`);
+  const pathMatch = TEXTURE_RELATIVE_PATH.exec(relativePath);
+  if (!pathMatch || pathMatch[1] !== binding.sha256) {
+    fail(`${label}.path must be the content-addressed textures/<sha256>.png path`);
+  }
+  if (!SHA256.test(binding.sha256)) fail(`${label}.sha256 must be a lowercase SHA-256 digest`);
+  if (!Number.isSafeInteger(binding.sizeBytes) || binding.sizeBytes <= 0) {
+    fail(`${label}.sizeBytes must be a positive safe integer`);
+  }
+  const colorSpace = object(binding.colorSpace, `${label}.colorSpace`);
+  const colorKeys = Object.keys(colorSpace).sort();
+  if (colorKeys.some((key) => key !== 'compressionSettings' && key !== 'srgb')) {
+    fail(`${label}.colorSpace contains unsupported metadata`);
+  }
+  if ('srgb' in colorSpace && typeof colorSpace.srgb !== 'boolean') {
+    fail(`${label}.colorSpace.srgb must be a boolean`);
+  }
+  if ('compressionSettings' in colorSpace) {
+    nonEmptyString(colorSpace.compressionSettings, `${label}.colorSpace.compressionSettings`);
+  }
+
+  const texturePath = resolve(outputRoot, relativePath);
+  containedPath(outputRoot, texturePath, label);
+  regularFile(texturePath, `${label} texture`, undefined);
+  const canonicalRoot = realpathSync(outputRoot);
+  const canonicalTexture = realpathSync(texturePath);
+  containedPath(canonicalRoot, canonicalTexture, `${label} texture`);
+  if (!hasHeader(texturePath, PNG_HEADER)) fail(`${label} texture is not a structurally valid PNG`);
+  const actual = hashAndSize(texturePath);
+  if (actual.sha256 !== binding.sha256 || actual.sizeBytes !== binding.sizeBytes) {
+    fail(`${label} texture bytes do not match the reviewed SHA-256 and size`);
+  }
+  return {
+    path: relativePath,
+    sha256: binding.sha256,
+    sizeBytes: binding.sizeBytes,
+    colorSpace,
+  };
+}
+
+function validateTextureDictionary(value, outputRoot, label) {
+  const dictionary = object(value, label);
+  const textures = [];
+  for (const [name, textureValue] of Object.entries(dictionary)) {
+    nonEmptyString(name, `${label} parameter name`);
+    textures.push(validateTextureBinding(textureValue, outputRoot, `${label}.${name}`));
+  }
+  return textures;
+}
+
+function validateMaterialSidecar(sidecarPath, profile, outputRoot) {
+  const info = regularFile(sidecarPath, `Material sidecar '${basename(sidecarPath)}'`, MAX_MATERIAL_SIDECAR_BYTES);
+  let sidecar;
+  try {
+    sidecar = JSON.parse(readFileSync(sidecarPath, 'utf8'));
+  } catch (error) {
+    fail(`Material sidecar '${basename(sidecarPath)}' is not valid JSON: ${error.message}`);
+  }
+  object(sidecar, `Material sidecar '${basename(sidecarPath)}'`);
+  exactKeys(sidecar, ['schemaVersion', 'asset', 'materials'], `Material sidecar '${basename(sidecarPath)}'`);
+  if (sidecar.schemaVersion !== MATERIAL_SIDECAR_SCHEMA) {
+    fail(`Material sidecar schemaVersion must be '${MATERIAL_SIDECAR_SCHEMA}'`);
+  }
+  const asset = object(sidecar.asset, 'Material sidecar asset');
+  exactKeys(asset, ['slug', 'sourceMeshAssetPath'], 'Material sidecar asset');
+  if (asset.slug !== profile.slug || asset.sourceMeshAssetPath !== profile.assetPath) {
+    fail(`Material sidecar asset identity does not match reviewed profile '${profile.slug}'`);
+  }
+  portableUnrealPath(asset.sourceMeshAssetPath, 'Material sidecar asset sourceMeshAssetPath');
+  if (!Array.isArray(sidecar.materials)) fail('Material sidecar materials must be an array');
+
+  const textures = [];
+  sidecar.materials.forEach((materialValue, index) => {
+    const label = `Material sidecar materials[${index}]`;
+    const material = object(materialValue, label);
+    exactKeys(material, [
+      'slotIndex',
+      'slotName',
+      'importedSlotName',
+      'sourceMaterialAssetPath',
+      'sourceRootMaterialAssetPath',
+      'parameters',
+    ], label);
+    if (material.slotIndex !== index) fail(`${label}.slotIndex must preserve ordered slot index ${index}`);
+    if (typeof material.slotName !== 'string' || typeof material.importedSlotName !== 'string') {
+      fail(`${label} slot names must be strings`);
+    }
+    portableUnrealPath(material.sourceMaterialAssetPath, `${label}.sourceMaterialAssetPath`);
+    portableUnrealPath(material.sourceRootMaterialAssetPath, `${label}.sourceRootMaterialAssetPath`);
+    const parameters = object(material.parameters, `${label}.parameters`);
+    exactKeys(parameters, ['scalars', 'vectors', 'textures'], `${label}.parameters`);
+    validateNumericDictionary(parameters.scalars, `${label}.parameters.scalars`);
+    validateVectorDictionary(parameters.vectors, `${label}.parameters.vectors`);
+    textures.push(...validateTextureDictionary(parameters.textures, outputRoot, `${label}.parameters.textures`));
+  });
+
+  const sidecarIdentity = hashAndSize(sidecarPath);
+  if (sidecarIdentity.sizeBytes !== info.size) fail(`Material sidecar '${basename(sidecarPath)}' changed during validation`);
+  const uniqueTextures = [...new Map(textures.map((texture) => [texture.path, texture])).values()]
+    .sort((left, right) => left.path.localeCompare(right.path));
+  return {
+    schemaVersion: MATERIAL_SIDECAR_SCHEMA,
+    path: basename(sidecarPath),
+    ...sidecarIdentity,
+    textures: uniqueTextures,
+  };
+}
+
+function validateTextureInventory(outputRoot, materialSidecars) {
+  const expected = new Set(materialSidecars.flatMap((sidecar) => sidecar.textures.map((texture) => texture.path)));
+  const texturesDir = join(outputRoot, 'textures');
+  if (!existsSync(texturesDir)) {
+    if (expected.size > 0) fail('Reviewed texture directory is missing');
+    return;
+  }
+  const directory = lstatSync(texturesDir);
+  if (!directory.isDirectory() || directory.isSymbolicLink()) {
+    fail('Reviewed texture directory must be a regular non-symlink directory');
+  }
+  const observed = new Set();
+  for (const entry of readdirSync(texturesDir, { withFileTypes: true })) {
+    const relativePath = `textures/${entry.name}`;
+    if (!entry.isFile() || entry.isSymbolicLink()) {
+      fail(`Reviewed texture inventory contains a non-file entry: ${relativePath}`);
+    }
+    if (!TEXTURE_RELATIVE_PATH.test(relativePath)) {
+      fail(`Reviewed texture inventory contains a non-content-addressed file: ${relativePath}`);
+    }
+    if (!expected.has(relativePath)) {
+      fail(`Reviewed texture inventory contains an unreferenced file: ${relativePath}`);
+    }
+    observed.add(relativePath);
+  }
+  if (observed.size !== expected.size) fail('Reviewed texture inventory is incomplete');
+}
+
+async function main() {
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(Buffer.from(chunk));
+  let request;
+  try {
+    request = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+  } catch (error) {
+    fail(`Bridge request is not valid JSON: ${error.message}`);
+  }
+
+  const { sourcePath, outputDir, profilePath } = validateRequest(request);
+  const profiles = validateProfile(readJsonFile(profilePath, 'Unreal asset profile'));
+  const project = findProject(sourcePath);
+  const outputs = profiles.map((profile) => join(outputDir, `${profile.slug}.fbx`));
+  const script = resolve(__dirname, '..', 'unreal', 'export_skeletal_mesh.py');
+  if (!existsSync(script)) fail(`Packaged Unreal Python exporter is missing: ${script}`);
+  if (!existsSync(outputDir) || !statSync(outputDir).isDirectory()) {
+    fail(`Bridge output directory does not exist: ${outputDir}`);
+  }
+  for (const output of outputs) {
+    if (existsSync(output)) fail(`Bridge output already exists before Unreal extraction: ${output}`);
+  }
+
+  const editorValue = nonEmptyString(process.env.HELIX_UNREAL_EDITOR, 'HELIX_UNREAL_EDITOR');
+  const paths = editorInvocationPaths(editorValue, project, script, outputs);
+  const environment = {
+    ...process.env,
+    HELIX_UNREAL_ASSET_PATH: profiles[0].assetPath,
+    HELIX_UNREAL_OUTPUT_FBX: paths.outputs[0],
+    HELIX_UNREAL_EXPORT_MORPH_TARGETS: profiles[0].exportMorphTargets ? '1' : '0',
+    HELIX_UNREAL_EXPORTS_JSON: JSON.stringify(profiles.map((profile, index) => ({
+      slug: profile.slug,
+      assetPath: profile.assetPath,
+      outputPath: paths.outputs[index],
+      exportMorphTargets: profile.exportMorphTargets,
+    }))),
+  };
+  const editorOutcome = await runEditor(paths.editor, [
+    paths.project,
+    `-ExecutePythonScript=${paths.script}`,
+    '-DisablePipInstall',
+    '-stdout',
+    '-FullStdOutLogOutput',
+    '-unattended',
+    '-nop4',
+    '-nosplash',
+    '-nosound',
+  ], editorEnvironment(environment, paths.wsl));
+
+  const invalidOutputs = outputs.map(validateFbxOutput).filter(Boolean);
+  if (invalidOutputs.length > 0) {
+    const suffix = editorOutcome.code === 0 && !editorOutcome.signal ? '' : `; ${editorFailure(editorOutcome)}`;
+    fail(`Unreal Editor did not produce the complete reviewed export set (${invalidOutputs.join(', ')})${suffix}`);
+  }
+  const materialSidecars = profiles.map((profile) => validateMaterialSidecar(
+    join(outputDir, `${profile.slug}.materials.json`),
+    profile,
+    outputDir,
+  ));
+  validateTextureInventory(outputDir, materialSidecars);
+  if (editorOutcome.signal) fail(editorFailure(editorOutcome));
+  if (editorOutcome.code !== 0) {
+    if (!isKnownBenignPlatformValidationShutdown(editorOutcome)) fail(editorFailure(editorOutcome));
+    process.stderr.write(
+      `HELIX Unreal Bridge warning: all reviewed FBXs were produced before the known benign UE ` +
+      `platform-validation shutdown exited ${editorOutcome.code}.` +
+      `${editorOutcome.tail ? ` ${editorOutcome.tail}` : ''}\n`,
+    );
+  }
+  process.stdout.write(JSON.stringify({
+    artifacts: profiles.map((profile, index) => ({
+      kind: 'format.fbx',
+      path: basename(outputs[index]),
+      metadata: {
+        unrealAsset: profile.assetPath,
+        exportMorphTargets: profile.exportMorphTargets,
+        materialSidecar: materialSidecars[index],
+      },
+    })),
+  }));
+}
+
+main().catch((error) => {
+  process.stderr.write(`HELIX Unreal Bridge: ${error instanceof Error ? error.message : String(error)}\n`);
+  process.exitCode = 1;
+});

package/bridge-plugins/helix.bridge.unreal/bridge-plugin.json

@@ -0,0 +1,40 @@
+{
+  "schemaVersion": "helix.bridge-plugin/1",
+  "id": "helix.bridge.unreal",
+  "name": "HELIX Unreal Bridge",
+  "version": "1.0.0",
+  "trust": "helix-verified",
+  "description": "Official Unreal Engine skeletal-mesh extraction adapter for HELIX Bridge.",
+  "permissions": [
+    "filesystem.read-source",
+    "filesystem.write-output",
+    "spawn-process",
+    "unrestricted-host-execution",
+    "unreal-editor"
+  ],
+  "capabilities": [
+    {
+      "id": "unreal.project.extract",
+      "stage": "extract",
+      "accepts": ["unreal.project"],
+      "produces": ["format.fbx"],
+      "targets": ["web", "unreal", "canonical"],
+      "permissions": [
+        "filesystem.read-source",
+        "filesystem.write-output",
+        "spawn-process",
+        "unrestricted-host-execution",
+        "unreal-editor"
+      ],
+      "requires": [
+        "tool:unreal-editor-commandlet",
+        "input:unrealAsset"
+      ],
+      "description": "Open the snapshotted Unreal project in the full editor and export one configured Skeletal Mesh to FBX.",
+      "command": {
+        "executable": "bin/unreal-skeletal-mesh-extract.js",
+        "timeoutSeconds": 3600
+      }
+    }
+  ]
+}