@hypersoniclabs/helix-cli 0.1.7 → 0.1.23

package/bridge-plugins/helix.bridge.unreal/test/handler.test.js

@@ -0,0 +1,417 @@
+'use strict';
+
+const assert = require('node:assert/strict');
+const { spawnSync } = require('node:child_process');
+const {
+  chmodSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  writeFileSync,
+} = require('node:fs');
+const { tmpdir } = require('node:os');
+const { join, resolve } = require('node:path');
+const test = require('node:test');
+
+const handler = resolve(__dirname, '..', 'bin', 'unreal-skeletal-mesh-extract.js');
+const benignPlatformValidationLog = [
+  'Running UnrealBuildTool: dotnet "..\\..\\Engine\\Binaries\\DotNET\\UnrealBuildTool\\UnrealBuildTool.dll" -Mode=ValidatePlatforms -OutputSDKs -AllPlatforms -project="FabImporterProject.uproject"',
+  "Unable to find required SDK version 'MainVersion' for platform VisionOS. Check your SDK.json files",
+].join('\n');
+
+function fixture(profileOverrides = {}) {
+  const root = mkdtempSync(join(tmpdir(), 'helix-unreal-adapter-'));
+  const project = join(root, 'project');
+  const output = join(root, 'output');
+  const profilePath = join(root, 'asset.json');
+  const invocationPath = join(root, 'invocation.json');
+  const editor = join(root, 'fake-editor.js');
+  mkdirSync(join(project, 'Content'), { recursive: true });
+  mkdirSync(output);
+  writeFileSync(join(project, 'Character.uproject'), '{}');
+  writeFileSync(profilePath, JSON.stringify({
+    schemaVersion: 'helix.bridge.unreal-asset/1',
+    slug: 'base-male',
+    assetPath: '/Game/Characters/Male/SK_BaseMale.SK_BaseMale',
+    exportMorphTargets: true,
+    ...profileOverrides,
+  }));
+  writeFileSync(editor, [
+    '#!/usr/bin/env node',
+    "const { createHash } = require('node:crypto');",
+    "const { mkdirSync, symlinkSync, writeFileSync } = require('node:fs');",
+    "const { dirname, join } = require('node:path');",
+    "const jobs = JSON.parse(process.env.HELIX_UNREAL_EXPORTS_JSON);",
+    "writeFileSync(process.env.HELIX_TEST_INVOCATION, JSON.stringify({ args: process.argv.slice(2), asset: process.env.HELIX_UNREAL_ASSET_PATH, morphs: process.env.HELIX_UNREAL_EXPORT_MORPH_TARGETS, jobs }));",
+    "const binaryFbx = Buffer.concat([Buffer.from('Kaydara FBX Binary  \\0\\x1a\\0', 'binary'), Buffer.alloc(32)]);",
+    "const asciiFbx = Buffer.from('; FBX 7.4.0 project file\\n; generated by the HELIX adapter test\\n');",
+    "const textureBytes = process.env.HELIX_TEST_TEXTURE_KIND === 'invalid-png' ? Buffer.from('not-png') : Buffer.concat([Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]), Buffer.from('fake-reviewed-png')]);",
+    "const textureSha = createHash('sha256').update(textureBytes).digest('hex');",
+    "const textureDirectory = join(dirname(jobs[0].outputPath), 'textures');",
+    "mkdirSync(textureDirectory, { recursive: true });",
+    "const texturePath = join(textureDirectory, textureSha + '.png');",
+    "writeFileSync(texturePath, textureBytes);",
+    "if (process.env.HELIX_TEST_TEXTURE_KIND === 'unreferenced') writeFileSync(join(textureDirectory, 'e'.repeat(64) + '.png'), textureBytes);",
+    "const failSlugs = new Set((process.env.HELIX_TEST_FAIL_SLUGS || '').split(',').filter(Boolean));",
+    "for (const job of jobs) {",
+    "  if (failSlugs.has(job.slug)) continue;", // simulates export_skeletal_mesh.py catching this job's failure and moving on without writing any output for it.
+    "  if (process.env.HELIX_TEST_OUTPUT_KIND === 'missing') continue;",
+    "  if (process.env.HELIX_TEST_OUTPUT_KIND === 'empty') writeFileSync(job.outputPath, Buffer.alloc(0));",
+    "  else if (process.env.HELIX_TEST_OUTPUT_KIND === 'corrupt') writeFileSync(job.outputPath, 'fake-fbx');",
+    "  else if (process.env.HELIX_TEST_OUTPUT_KIND === 'ascii') writeFileSync(job.outputPath, asciiFbx);",
+    "  else writeFileSync(job.outputPath, binaryFbx);",
+    "  if (process.env.HELIX_TEST_SIDECAR_KIND === 'missing') continue;",
+    "  const bindingSha = process.env.HELIX_TEST_SIDECAR_KIND === 'hash-mismatch' ? 'f'.repeat(64) : textureSha;",
+    "  const bindingPath = process.env.HELIX_TEST_SIDECAR_KIND === 'escape' ? '../escaped.png' : 'textures/' + bindingSha + '.png';",
+    "  const colorSpace = { srgb: true, compressionSettings: 'TC_Default' };",
+    "  if (process.env.HELIX_TEST_SIDECAR_KIND === 'flip-green') colorSpace.flipGreenChannel = true;",
+    "  const sidecar = { schemaVersion: 'helix.bridge.unreal-material-sidecar/1', asset: { slug: job.slug, sourceMeshAssetPath: job.assetPath }, materials: [{ slotIndex: 0, slotName: 'Body', importedSlotName: 'Body_skin00', sourceMaterialAssetPath: '/Game/Materials/MI_Body.MI_Body', sourceRootMaterialAssetPath: '/Game/Materials/M_Body.M_Body', parameters: { scalars: { Roughness: 0.5 }, vectors: { Tint: { r: 1, g: 0.5, b: 0.25, a: 1 } }, textures: { BaseColor: { sourceAssetPath: '/Game/Textures/T_Body.T_Body', path: bindingPath, sha256: bindingSha, sizeBytes: textureBytes.length, colorSpace } } } }] };",
+    "  const sidecarPath = join(dirname(job.outputPath), job.slug + '.materials.json');",
+    "  if (process.env.HELIX_TEST_SIDECAR_KIND === 'corrupt') writeFileSync(sidecarPath, '{');",
+    "  else if (process.env.HELIX_TEST_SIDECAR_KIND === 'symlink') symlinkSync(process.env.HELIX_TEST_INVOCATION, sidecarPath);",
+    "  else writeFileSync(sidecarPath, JSON.stringify(sidecar));",
+    "}",
+    // Simulates export_skeletal_mesh.py's own '_export-results.json' per-asset outcome manifest
+    // (see EXPORT_RESULTS_SCHEMA/EXPORT_RESULTS_FILENAME) so the handler's partial-batch
+    // path — reading that manifest rather than only inferring outcomes from file presence —
+    // gets real end-to-end coverage here, not just in exporter.test.js's direct Python tests.
+    "if (process.env.HELIX_TEST_FAIL_SLUGS) {",
+    "  const resultsPath = join(dirname(jobs[0].outputPath), '_export-results.json');",
+    "  const results = jobs.map((job) => failSlugs.has(job.slug)",
+    "    ? { slug: job.slug, assetPath: job.assetPath, outputPath: job.outputPath, status: 'failed', error: `Unreal asset ${JSON.stringify(job.assetPath)} is MaterialInstanceConstant, not a SkeletalMesh` }",
+    "    : { slug: job.slug, assetPath: job.assetPath, outputPath: job.outputPath, status: 'succeeded' });",
+    "  writeFileSync(resultsPath, JSON.stringify({ schemaVersion: 'helix.bridge.unreal-export-results/1', results }));",
+    "}",
+    "if (process.env.HELIX_TEST_EDITOR_LOG) process.stderr.write(process.env.HELIX_TEST_EDITOR_LOG);",
+    "if (process.env.HELIX_TEST_ABSLOG_CONTENT) {",
+    "  const abslogArg = process.argv.slice(2).find((arg) => arg.startsWith('-abslog='));",
+    "  if (abslogArg) writeFileSync(abslogArg.slice('-abslog='.length), process.env.HELIX_TEST_ABSLOG_CONTENT);",
+    "}",
+    "if (process.env.HELIX_TEST_EDITOR_SIGNAL) process.kill(process.pid, process.env.HELIX_TEST_EDITOR_SIGNAL);",
+    "if (process.env.HELIX_TEST_EDITOR_EXIT) process.exit(Number(process.env.HELIX_TEST_EDITOR_EXIT));",
+  ].join('\n'));
+  chmodSync(editor, 0o755);
+  const request = {
+    schemaVersion: 'helix.bridge-plugin-request/1',
+    capability: 'unreal.project.extract',
+    source: { source: project, sourceKind: 'unreal.project' },
+    inputs: { unrealAsset: { path: profilePath, sha256: '0'.repeat(64), sizeBytes: 1 } },
+    outputDir: output,
+    target: 'web',
+    deterministicKey: 'test',
+    input: null,
+  };
+  return { root, project, output, profilePath, invocationPath, editor, request };
+}
+
+function run(entry, extraEnvironment = {}) {
+  return spawnSync(process.execPath, [handler], {
+    input: JSON.stringify(entry.request),
+    encoding: 'utf8',
+    env: {
+      PATH: process.env.PATH,
+      HELIX_UNREAL_EDITOR: entry.editor,
+      HELIX_TEST_INVOCATION: entry.invocationPath,
+      ...extraEnvironment,
+    },
+  });
+}
+
+test('exports one configured skeletal mesh with the full Unreal editor script', () => {
+  const entry = fixture();
+  const result = run(entry);
+  assert.equal(result.status, 0, result.stderr);
+  const response = JSON.parse(result.stdout);
+  assert.equal(response.artifacts[0].kind, 'format.fbx');
+  assert.equal(response.artifacts[0].path, 'base-male.fbx');
+  assert.equal(response.artifacts[0].metadata.unrealAsset, '/Game/Characters/Male/SK_BaseMale.SK_BaseMale');
+  assert.equal(response.artifacts[0].metadata.exportMorphTargets, true);
+  assert.match(response.artifacts[0].metadata.materialSidecar.sha256, /^[a-f0-9]{64}$/);
+  assert.equal(response.artifacts[0].metadata.materialSidecar.path, 'base-male.materials.json');
+  assert.equal(response.artifacts[0].metadata.materialSidecar.schemaVersion, 'helix.bridge.unreal-material-sidecar/1');
+  assert.equal(response.artifacts[0].metadata.materialSidecar.textures.length, 1);
+  assert.match(response.artifacts[0].metadata.materialSidecar.textures[0].path, /^textures\/[a-f0-9]{64}\.png$/);
+  const invocation = JSON.parse(readFileSync(entry.invocationPath, 'utf8'));
+  assert.equal(invocation.asset, '/Game/Characters/Male/SK_BaseMale.SK_BaseMale');
+  assert.equal(invocation.morphs, '1');
+  assert.equal(invocation.args[0], join(entry.project, 'Character.uproject'));
+  assert.match(invocation.args[1], /^-ExecutePythonScript=.*export_skeletal_mesh\.py$/);
+  assert.ok(invocation.args.includes('-stdout'));
+  assert.ok(invocation.args.includes('-FullStdOutLogOutput'));
+  assert.ok(invocation.args.includes('-log'));
+  assert.ok(invocation.args.some((arg) => arg.startsWith('-abslog=')));
+  assert.match(readFileSync(join(entry.output, 'base-male.fbx'), 'binary'), /^Kaydara FBX Binary/);
+  const sidecar = JSON.parse(readFileSync(join(entry.output, 'base-male.materials.json'), 'utf8'));
+  assert.equal(sidecar.materials[0].parameters.scalars.Roughness, 0.5);
+  assert.deepEqual(sidecar.materials[0].parameters.vectors.Tint, { r: 1, g: 0.5, b: 0.25, a: 1 });
+});
+
+test('mounts an ExplicitlyLoaded Game Features plugin before extraction, and leaves other plugins alone', () => {
+  const entry = fixture();
+  const explicitPluginDir = join(entry.project, 'Plugins', 'HelixCharacterCreator');
+  mkdirSync(join(explicitPluginDir, 'Content'), { recursive: true });
+  const explicitPluginPath = join(explicitPluginDir, 'HelixCharacterCreator.uplugin');
+  writeFileSync(explicitPluginPath, JSON.stringify({
+    FileVersion: 3,
+    FriendlyName: 'HelixCharacterCreator',
+    Category: 'Game Features',
+    CanContainContent: true,
+    ExplicitlyLoaded: true,
+    BuiltInInitialFeatureState: 'Registered',
+  }));
+  chmodSync(explicitPluginPath, 0o444); // Perforce-style read-only, like the real content.
+
+  const implicitPluginDir = join(entry.project, 'Plugins', 'SomeOrdinaryPlugin');
+  mkdirSync(join(implicitPluginDir, 'Content'), { recursive: true });
+  const implicitPluginPath = join(implicitPluginDir, 'SomeOrdinaryPlugin.uplugin');
+  writeFileSync(implicitPluginPath, JSON.stringify({
+    FileVersion: 3,
+    FriendlyName: 'SomeOrdinaryPlugin',
+    CanContainContent: true,
+    ExplicitlyLoaded: false,
+  }));
+
+  const result = run(entry);
+  assert.equal(result.status, 0, result.stderr);
+
+  const patched = JSON.parse(readFileSync(explicitPluginPath, 'utf8'));
+  assert.equal(patched.ExplicitlyLoaded, false);
+  assert.equal(patched.Category, 'Game Features', 'only the loading gate changes, not the plugin identity');
+
+  const untouched = JSON.parse(readFileSync(implicitPluginPath, 'utf8'));
+  assert.equal(untouched.ExplicitlyLoaded, false);
+});
+
+test('accepts a structurally valid ASCII FBX export', () => {
+  const entry = fixture();
+  const result = run(entry, { HELIX_TEST_OUTPUT_KIND: 'ascii' });
+  assert.equal(result.status, 0, result.stderr);
+  assert.match(readFileSync(join(entry.output, 'base-male.fbx'), 'ascii'), /^; FBX 7\.4\.0 project file/);
+});
+
+test('accepts complete FBXs for the known UE platform-validation shutdown failure', () => {
+  const entry = fixture();
+  const result = run(entry, {
+    HELIX_TEST_EDITOR_EXIT: '5',
+    HELIX_TEST_EDITOR_LOG: benignPlatformValidationLog,
+  });
+  assert.equal(result.status, 0, result.stderr);
+  assert.match(result.stderr, /known benign UE platform-validation shutdown exited 5/);
+  assert.match(readFileSync(join(entry.output, 'base-male.fbx'), 'binary'), /^Kaydara FBX Binary/);
+});
+
+test('rejects complete FBXs when a nonzero editor exit has an unrecognized cause', () => {
+  const entry = fixture();
+  const result = run(entry, {
+    HELIX_TEST_EDITOR_EXIT: '5',
+    HELIX_TEST_EDITOR_LOG: 'Fatal error: shader compilation failed',
+  });
+  assert.equal(result.status, 1);
+  assert.match(result.stderr, /Unreal Editor failed with exit 5/);
+  assert.match(result.stderr, /shader compilation failed/);
+});
+
+test('rejects the known platform-validation log with any other exit code', () => {
+  const entry = fixture();
+  const result = run(entry, {
+    HELIX_TEST_EDITOR_EXIT: '6',
+    HELIX_TEST_EDITOR_LOG: benignPlatformValidationLog,
+  });
+  assert.equal(result.status, 1);
+  assert.match(result.stderr, /Unreal Editor failed with exit 6/);
+});
+
+test('rejects a corrupt file even when Unreal exits successfully', () => {
+  const entry = fixture();
+  const result = run(entry, { HELIX_TEST_OUTPUT_KIND: 'corrupt' });
+  assert.equal(result.status, 1);
+  assert.match(result.stderr, /not a structurally valid FBX/);
+});
+
+test('surfaces the real engine log tail, not just the truncated stdout tail, when the export set is incomplete', () => {
+  const entry = fixture();
+  const result = run(entry, {
+    HELIX_TEST_OUTPUT_KIND: 'missing',
+    HELIX_TEST_ABSLOG_CONTENT: 'LogPython: Error: Unable to load Unreal asset — this is the real engine log, not stdout',
+  });
+  assert.equal(result.status, 1);
+  assert.match(result.stderr, /did not produce the complete reviewed export set/);
+  assert.match(result.stderr, /Unreal Editor engine log/);
+  assert.match(result.stderr, /Unable to load Unreal asset — this is the real engine log, not stdout/);
+});
+
+test('rejects missing and empty export files', async (t) => {
+  for (const outputKind of ['missing', 'empty']) {
+    await t.test(outputKind, () => {
+      const entry = fixture();
+      const result = run(entry, { HELIX_TEST_OUTPUT_KIND: outputKind });
+      assert.equal(result.status, 1);
+      assert.match(result.stderr, /did not produce the complete reviewed export set/);
+    });
+  }
+});
+
+test('rejects missing, malformed, escaped, or digest-mismatched material sidecars', async (t) => {
+  for (const sidecarKind of ['missing', 'corrupt', 'escape', 'hash-mismatch', 'symlink']) {
+    await t.test(sidecarKind, () => {
+      const entry = fixture();
+      const result = run(entry, { HELIX_TEST_SIDECAR_KIND: sidecarKind });
+      assert.equal(result.status, 1);
+      assert.match(result.stderr, /Material sidecar|content-addressed|regular non-symlink|reviewed SHA-256/i);
+    });
+  }
+});
+
+test('rejects invalid or unreferenced texture output', async (t) => {
+  for (const textureKind of ['invalid-png', 'unreferenced']) {
+    await t.test(textureKind, () => {
+      const entry = fixture();
+      const result = run(entry, { HELIX_TEST_TEXTURE_KIND: textureKind });
+      assert.equal(result.status, 1);
+      assert.match(result.stderr, /structurally valid PNG|unreferenced file/i);
+    });
+  }
+});
+
+test('rejects editor termination by signal even when complete FBXs exist', () => {
+  const entry = fixture();
+  const result = run(entry, { HELIX_TEST_EDITOR_SIGNAL: 'SIGTERM' });
+  assert.equal(result.status, 1);
+  assert.match(result.stderr, /Unreal Editor failed with signal SIGTERM/);
+});
+
+test('accepts plugin-mounted Unreal virtual asset paths', () => {
+  const entry = fixture({
+    assetPath: '/HelixCharacterCreator/Characters/Clothes/Man/M_Cap+EV1/M_Cap+EV1',
+  });
+  const result = run(entry);
+  assert.equal(result.status, 0, result.stderr);
+  const invocation = JSON.parse(readFileSync(entry.invocationPath, 'utf8'));
+  assert.equal(invocation.asset, '/HelixCharacterCreator/Characters/Clothes/Man/M_Cap+EV1/M_Cap+EV1');
+});
+
+test('exports a reviewed modular asset set in one editor invocation', () => {
+  const entry = fixture();
+  writeFileSync(entry.profilePath, JSON.stringify({
+    schemaVersion: 'helix.bridge.unreal-asset-set/1',
+    assets: [
+      { slug: 'base-male', assetPath: '/Game/Characters/Male/SK_BaseMale', exportMorphTargets: true },
+      { slug: 'male-top', assetPath: '/Game/Characters/Male/SK_Top', exportMorphTargets: false },
+    ],
+  }));
+  const result = run(entry);
+  assert.equal(result.status, 0, result.stderr);
+  const response = JSON.parse(result.stdout);
+  assert.deepEqual(response.artifacts.map((artifact) => artifact.path), ['base-male.fbx', 'male-top.fbx']);
+  const invocation = JSON.parse(readFileSync(entry.invocationPath, 'utf8'));
+  assert.equal(invocation.jobs.length, 2);
+  assert.equal(invocation.jobs[1].assetPath, '/Game/Characters/Male/SK_Top');
+  assert.equal(invocation.jobs[1].exportMorphTargets, false);
+  assert.match(readFileSync(join(entry.output, 'male-top.fbx'), 'binary'), /^Kaydara FBX Binary/);
+});
+
+test('delivers the successful half of a batch when one asset fails, instead of discarding the whole run', () => {
+  // Regression for batch-backlog.md item 13: a batch naming SKM_M_Denim_Jacket (which won't
+  // load as a SkeletalMesh) + Combat Boots used to produce NOTHING — Combat Boots was never
+  // even attempted because the first failure aborted the whole extraction.
+  const entry = fixture();
+  writeFileSync(entry.profilePath, JSON.stringify({
+    schemaVersion: 'helix.bridge.unreal-asset-set/1',
+    assets: [
+      { slug: 'denim-jacket', assetPath: '/Game/Characters/SKM_M_Denim_Jacket', exportMorphTargets: true },
+      { slug: 'combat-boots', assetPath: '/Game/Characters/SKM_M_Combat_Boots', exportMorphTargets: true },
+    ],
+  }));
+  const result = run(entry, { HELIX_TEST_FAIL_SLUGS: 'denim-jacket' });
+  assert.equal(result.status, 0, result.stderr);
+
+  const response = JSON.parse(result.stdout);
+  assert.deepEqual(response.artifacts.map((artifact) => artifact.path), ['combat-boots.fbx']);
+  assert.equal(response.artifacts[0].metadata.unrealAsset, '/Game/Characters/SKM_M_Combat_Boots');
+  assert.deepEqual(response.failures, [{
+    slug: 'denim-jacket',
+    assetPath: '/Game/Characters/SKM_M_Denim_Jacket',
+    reason: 'Unreal asset "/Game/Characters/SKM_M_Denim_Jacket" is MaterialInstanceConstant, not a SkeletalMesh',
+  }]);
+
+  assert.match(result.stderr, /denim-jacket.*failed and was.*skipped/s);
+  assert.match(readFileSync(join(entry.output, 'combat-boots.fbx'), 'binary'), /^Kaydara FBX Binary/);
+  const sidecar = JSON.parse(readFileSync(join(entry.output, 'combat-boots.materials.json'), 'utf8'));
+  assert.equal(sidecar.asset.slug, 'combat-boots');
+});
+
+test('still fails the whole batch when every asset in it fails', () => {
+  const entry = fixture();
+  writeFileSync(entry.profilePath, JSON.stringify({
+    schemaVersion: 'helix.bridge.unreal-asset-set/1',
+    assets: [
+      { slug: 'base-male', assetPath: '/Game/Characters/Male/SK_BaseMale', exportMorphTargets: true },
+      { slug: 'male-top', assetPath: '/Game/Characters/Male/SK_Top', exportMorphTargets: false },
+    ],
+  }));
+  const result = run(entry, { HELIX_TEST_FAIL_SLUGS: 'base-male,male-top' });
+  assert.equal(result.status, 1);
+  assert.match(result.stderr, /did not produce the complete reviewed export set/);
+  assert.match(result.stderr, /base-male\.fbx.*MaterialInstanceConstant/);
+  assert.match(result.stderr, /male-top\.fbx.*MaterialInstanceConstant/);
+});
+
+test('a crashed editor still voids the whole batch even if the results manifest shows a success', () => {
+  // Per-asset isolation only ever softens a caught Python exception. It must not weaken the
+  // existing hard gate on the editor process itself dying — that state can't be trusted.
+  const entry = fixture();
+  writeFileSync(entry.profilePath, JSON.stringify({
+    schemaVersion: 'helix.bridge.unreal-asset-set/1',
+    assets: [
+      { slug: 'base-male', assetPath: '/Game/Characters/Male/SK_BaseMale', exportMorphTargets: true },
+      { slug: 'male-top', assetPath: '/Game/Characters/Male/SK_Top', exportMorphTargets: false },
+    ],
+  }));
+  const result = run(entry, { HELIX_TEST_FAIL_SLUGS: 'male-top', HELIX_TEST_EDITOR_SIGNAL: 'SIGTERM' });
+  assert.equal(result.status, 1);
+  assert.match(result.stderr, /Unreal Editor failed with signal SIGTERM/);
+});
+
+test('rejects malformed asset profiles before starting Unreal', () => {
+  const entry = fixture({ assetPath: '../Content/SK_BaseMale' });
+  const result = run(entry);
+  assert.equal(result.status, 1);
+  assert.match(result.stderr, /mounted virtual Unreal asset path/);
+});
+
+test('requires exactly one uproject in the immutable source snapshot', () => {
+  const entry = fixture();
+  writeFileSync(join(entry.project, 'Other.uproject'), '{}');
+  const result = run(entry);
+  assert.equal(result.status, 1);
+  assert.match(result.stderr, /exactly one \.uproject file; found 2/);
+});
+
+test('does not walk into Binaries/Intermediate/Saved/DerivedDataCache when finding the .uproject', () => {
+  const entry = fixture();
+  // A real Perforce-synced Unreal project's build/cache directories can hold hundreds of
+  // thousands of files; simulate that here with just enough entries (and a decoy .uproject
+  // inside one of them) to prove the walk skips them entirely rather than merely tolerating them.
+  for (const excluded of ['Binaries', 'Intermediate', 'Saved', 'DerivedDataCache']) {
+    const dir = join(entry.project, excluded, 'Nested');
+    mkdirSync(dir, { recursive: true });
+    for (let i = 0; i < 10; i += 1) writeFileSync(join(dir, `junk-${i}.bin`), '');
+  }
+  writeFileSync(join(entry.project, 'Intermediate', 'Decoy.uproject'), '{}');
+  const result = run(entry);
+  assert.equal(result.status, 0, result.stderr);
+  const response = JSON.parse(result.stdout);
+  assert.equal(response.artifacts[0].kind, 'format.fbx');
+});
+
+test('accepts a material sidecar texture binding that records flipGreenChannel', () => {
+  // export_skeletal_mesh.py (texture_color_space) has recorded flipGreenChannel for every
+  // texture since the "Flip Green Channel" DirectX/OpenGL convention was added, but this
+  // handler's own sidecar validator never learned the key — every real export failed with
+  // "colorSpace contains unsupported metadata" until now.
+  const entry = fixture();
+  const result = run(entry, { HELIX_TEST_SIDECAR_KIND: 'flip-green' });
+  assert.equal(result.status, 0, result.stderr);
+  const sidecar = JSON.parse(readFileSync(join(entry.output, 'base-male.materials.json'), 'utf8'));
+  assert.equal(sidecar.materials[0].parameters.textures.BaseColor.colorSpace.flipGreenChannel, true);
+});