@helix3/helix-cli 0.1.18-helix3.273 → 0.1.18-helix3.275

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

@@ -39,6 +39,13 @@ 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;
+// Mirrors unreal/export_skeletal_mesh.py's EXPORT_RESULTS_SCHEMA/EXPORT_RESULTS_FILENAME
+// (kept in sync by hand: that script runs standalone inside UnrealEditor's Python VM, not
+// through this built JS, so it cannot import from here). Optional per-asset outcome manifest:
+// absent on an older exporter build, or when the editor died before writing anything, in
+// which case this handler falls back to file-based validation alone (see readExportResults).
+const EXPORT_RESULTS_SCHEMA = 'helix.bridge.unreal-export-results/1';
+const EXPORT_RESULTS_FILENAME = '_export-results.json';
 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$/;
@@ -488,6 +495,34 @@ function validateFbxOutput(output) {
   return binary || ascii ? null : `'${basename(output)}' is not a structurally valid FBX`;
 }
 
+function readExportResults(resultsPath) {
+  if (!existsSync(resultsPath)) return null;
+  try {
+    const parsed = JSON.parse(readFileSync(resultsPath, 'utf8'));
+    if (parsed?.schemaVersion !== EXPORT_RESULTS_SCHEMA || !Array.isArray(parsed.results)) return null;
+    const bySlug = new Map();
+    for (const entry of parsed.results) {
+      if (!entry || typeof entry.slug !== 'string' || typeof entry.status !== 'string') continue;
+      bySlug.set(entry.slug, { status: entry.status, error: typeof entry.error === 'string' ? entry.error : undefined });
+    }
+    return bySlug;
+  } catch {
+    // A missing or unreadable manifest just means this handler falls back to file-based
+    // validation alone; it should never be the reason a batch that otherwise succeeded fails.
+    return null;
+  }
+}
+
+function assetOutcome(profile, output, exportResults) {
+  const fileIssue = validateFbxOutput(output);
+  const recorded = exportResults?.get(profile.slug);
+  if (recorded?.status === 'failed') {
+    return { profile, output, ok: false, reason: recorded.error || fileIssue || 'Unreal reported this asset failed to export' };
+  }
+  if (fileIssue) return { profile, output, ok: false, reason: fileIssue };
+  return { profile, output, ok: true };
+}
+
 function validateNumericDictionary(value, label) {
   const dictionary = object(value, label);
   for (const [name, number] of Object.entries(dictionary)) {
@@ -705,21 +740,37 @@ async function main() {
     `-abslog=${paths.log}`,
   ], editorEnvironment(environment, paths.wsl), paths.wsl);
 
-  const invalidOutputs = outputs.map(validateFbxOutput).filter(Boolean);
-  if (invalidOutputs.length > 0) {
+  // Per-asset isolation: one bad asset in a multi-asset batch (wrong type, won't load in the
+  // Unreal Editor, corrupt material, ...) must not discard every other asset that exported
+  // cleanly. export_skeletal_mesh.py now catches a per-asset export failure and continues, so
+  // this reads its optional results manifest (falling back to file-based validation alone if
+  // it is absent) and only fails the WHOLE batch when nothing usable came out of it. See
+  // batch-backlog.md item 13.
+  const exportResults = readExportResults(join(outputDir, EXPORT_RESULTS_FILENAME));
+  const outcomes = profiles.map((profile, index) => assetOutcome(profile, outputs[index], exportResults));
+  const succeeded = outcomes.filter((outcome) => outcome.ok);
+  const failed = outcomes.filter((outcome) => !outcome.ok);
+
+  if (succeeded.length === 0) {
     const suffix = editorOutcome.code === 0 && !editorOutcome.signal ? '' : `; ${editorFailure(editorOutcome)}`;
     const engineLogTail = readEngineLogTail(engineLogPath, ENGINE_LOG_TAIL_BYTES);
     const logSuffix = engineLogTail
       ? `\nUnreal Editor engine log (${engineLogPath}):\n${engineLogTail}`
       : `\n(Unreal Editor engine log not found at ${engineLogPath})`;
-    fail(`Unreal Editor did not produce the complete reviewed export set (${invalidOutputs.join(', ')})${suffix}${logSuffix}`);
+    const reasons = failed.map((outcome) => `${basename(outcome.output)}: ${outcome.reason}`).join(', ');
+    fail(`Unreal Editor did not produce the complete reviewed export set (${reasons})${suffix}${logSuffix}`);
   }
-  const materialSidecars = profiles.map((profile) => validateMaterialSidecar(
-    join(outputDir, `${profile.slug}.materials.json`),
-    profile,
+  const materialSidecars = succeeded.map((outcome) => validateMaterialSidecar(
+    join(outputDir, `${outcome.profile.slug}.materials.json`),
+    outcome.profile,
     outputDir,
   ));
   validateTextureInventory(outputDir, materialSidecars);
+
+  // A crashed or abnormally-terminated editor still voids the WHOLE batch even if some FBXs
+  // happen to be valid on disk — unlike a caught per-asset export exception, we cannot trust
+  // that any of this run's output is complete. This matches the pre-existing behavior for a
+  // fully successful editor exit.
   if (editorOutcome.signal) fail(editorFailure(editorOutcome));
   if (editorOutcome.code !== 0) {
     if (!isKnownBenignPlatformValidationShutdown(editorOutcome)) fail(editorFailure(editorOutcome));
@@ -729,16 +780,29 @@ async function main() {
       `${editorOutcome.tail ? ` ${editorOutcome.tail}` : ''}\n`,
     );
   }
+
+  for (const outcome of failed) {
+    process.stderr.write(
+      `HELIX Unreal Bridge: asset '${outcome.profile.slug}' (${outcome.profile.assetPath}) failed and was ` +
+      `skipped; the rest of the batch was still delivered: ${outcome.reason}\n`,
+    );
+  }
+
   process.stdout.write(JSON.stringify({
-    artifacts: profiles.map((profile, index) => ({
+    artifacts: succeeded.map((outcome, index) => ({
       kind: 'format.fbx',
-      path: basename(outputs[index]),
+      path: basename(outcome.output),
       metadata: {
-        unrealAsset: profile.assetPath,
-        exportMorphTargets: profile.exportMorphTargets,
+        unrealAsset: outcome.profile.assetPath,
+        exportMorphTargets: outcome.profile.exportMorphTargets,
         materialSidecar: materialSidecars[index],
       },
     })),
+    failures: failed.map((outcome) => ({
+      slug: outcome.profile.slug,
+      assetPath: outcome.profile.assetPath,
+      reason: outcome.reason,
+    })),
   }));
 }
 

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

@@ -2,7 +2,7 @@
 
 const assert = require('node:assert/strict');
 const { spawnSync } = require('node:child_process');
-const { mkdirSync, mkdtempSync, readFileSync, writeFileSync } = require('node:fs');
+const { existsSync, mkdirSync, mkdtempSync, readFileSync, writeFileSync } = require('node:fs');
 const { tmpdir } = require('node:os');
 const { join, resolve } = require('node:path');
 const test = require('node:test');
@@ -99,6 +99,8 @@ class EditorAssetLibrary:
             return None
         if os.environ.get('HELIX_FAKE_UNREAL_WRONG_TYPE') == '1':
             return _WrongAsset()
+        if path == os.environ.get('HELIX_FAKE_UNREAL_WRONG_TYPE_PATH'):
+            return _WrongAsset()
         return SkeletalMesh(path)
 
 class FbxExportOption:
@@ -317,6 +319,90 @@ test('omits non-Texture2D material parameters while preserving portable Texture2
   assert.equal(observed.at(-1).kind, 'quit_editor');
 });
 
+test('isolates a per-asset failure: the rest of the batch still exports and a results manifest records both outcomes', () => {
+  // Regression for batch-backlog.md item 13: `SKM_M_Denim_Jacket` (a MaterialInstanceConstant,
+  // not a SkeletalMesh) used to throw out of the batch loop and abort the whole UnrealEditor
+  // process, so `Combat Boots` right after it in the same batch was never even attempted.
+  const entry = fixture();
+  const outputs = [
+    join(entry.outputDir, 'denim-jacket.fbx'),
+    join(entry.outputDir, 'combat-boots.fbx'),
+  ];
+  const jobs = [
+    { slug: 'denim-jacket', assetPath: '/Game/Characters/SKM_M_Denim_Jacket', outputPath: outputs[0], exportMorphTargets: true },
+    { slug: 'combat-boots', assetPath: '/Game/Characters/SKM_M_Combat_Boots', outputPath: outputs[1], exportMorphTargets: true },
+  ];
+  const result = run(entry, {
+    HELIX_UNREAL_EXPORTS_JSON: JSON.stringify(jobs),
+    HELIX_FAKE_UNREAL_WRONG_TYPE_PATH: '/Game/Characters/SKM_M_Denim_Jacket',
+  });
+  // The exporter itself exits zero: something usable came out of this batch, so it is up to
+  // the Node handler (see handler.test.js) to decide how to report the mixed outcome upward,
+  // not for the exporter to make the whole run look like a hard failure.
+  assert.equal(result.status, 0, result.stderr);
+
+  const observed = events(entry);
+  assert.deepEqual(observed.filter((event) => event.kind === 'load_asset').map((event) => event.path), [
+    '/Game/Characters/SKM_M_Denim_Jacket',
+    '/Game/Characters/SKM_M_Combat_Boots',
+  ], 'combat-boots must still be attempted after denim-jacket fails');
+  assert.ok(
+    observed.some((event) => event.kind === 'log_error' && /SKM_M_Denim_Jacket/.test(event.message) && /not a SkeletalMesh/.test(event.message)),
+  );
+
+  assert.equal(existsSync(join(entry.outputDir, 'denim-jacket.fbx')), false);
+  assert.match(readFileSync(join(entry.outputDir, 'combat-boots.fbx'), 'binary'), /^Kaydara FBX Binary/);
+  const bootsSidecar = JSON.parse(readFileSync(join(entry.outputDir, 'combat-boots.materials.json'), 'utf8'));
+  assert.equal(bootsSidecar.asset.slug, 'combat-boots');
+
+  const manifest = JSON.parse(readFileSync(join(entry.outputDir, '_export-results.json'), 'utf8'));
+  assert.equal(manifest.schemaVersion, 'helix.bridge.unreal-export-results/1');
+  const bySlug = Object.fromEntries(manifest.results.map((entryResult) => [entryResult.slug, entryResult]));
+  assert.equal(bySlug['denim-jacket'].status, 'failed');
+  assert.match(bySlug['denim-jacket'].error, /not a SkeletalMesh/);
+  assert.equal(bySlug['combat-boots'].status, 'succeeded');
+  assert.equal(observed.at(-1).kind, 'quit_editor', 'the editor must still shut down cleanly after a partial batch');
+});
+
+test('exits zero when a batch fully succeeds despite an earlier asset in the same batch failing', () => {
+  // The overall process exit code should reflect whether the batch produced anything usable
+  // at all, not merely whether the FIRST asset happened to succeed — this is what lets the
+  // Node handler treat a partial batch as a deliverable result rather than a hard failure.
+  const entry = fixture();
+  const outputs = [join(entry.outputDir, 'body.fbx'), join(entry.outputDir, 'top.fbx')];
+  const jobs = [
+    { slug: 'body', assetPath: '/Game/Broken', outputPath: outputs[0], exportMorphTargets: true },
+    { slug: 'top', assetPath: '/Game/Top', outputPath: outputs[1], exportMorphTargets: true },
+  ];
+  const result = run(entry, {
+    HELIX_UNREAL_EXPORTS_JSON: JSON.stringify(jobs),
+    HELIX_FAKE_UNREAL_WRONG_TYPE_PATH: '/Game/Broken',
+  });
+  assert.equal(result.status, 0, result.stderr);
+  assert.match(readFileSync(outputs[1], 'binary'), /^Kaydara FBX Binary/);
+  const manifest = JSON.parse(readFileSync(join(entry.outputDir, '_export-results.json'), 'utf8'));
+  const bySlug = Object.fromEntries(manifest.results.map((entryResult) => [entryResult.slug, entryResult]));
+  assert.equal(bySlug.body.status, 'failed', 'the manifest still records the real failure even though the batch exits zero');
+  assert.equal(bySlug.top.status, 'succeeded');
+});
+
+test('reports every asset failed, with no partial output, when an entire batch fails', () => {
+  const entry = fixture();
+  const outputs = [join(entry.outputDir, 'body.fbx'), join(entry.outputDir, 'top.fbx')];
+  const jobs = [
+    { slug: 'body', assetPath: '/Game/Body', outputPath: outputs[0], exportMorphTargets: true },
+    { slug: 'top', assetPath: '/Game/Top', outputPath: outputs[1], exportMorphTargets: true },
+  ];
+  const result = run(entry, {
+    HELIX_UNREAL_EXPORTS_JSON: JSON.stringify(jobs),
+    HELIX_FAKE_UNREAL_WRONG_TYPE: '1',
+  });
+  assert.notEqual(result.status, 0);
+  assert.match(result.stderr, /Every asset in this batch failed to export/);
+  const manifest = JSON.parse(readFileSync(join(entry.outputDir, '_export-results.json'), 'utf8'));
+  assert.ok(manifest.results.every((entryResult) => entryResult.status === 'failed'));
+});
+
 test('fails atomically when Unreal cannot export a referenced Texture2D', () => {
   const entry = fixture();
   const result = run(entry, {

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

@@ -52,7 +52,9 @@ function fixture(profileOverrides = {}) {
     "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');",
@@ -69,6 +71,17 @@ function fixture(profileOverrides = {}) {
     "  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='));",
@@ -297,6 +310,68 @@ test('exports a reviewed modular asset set in one editor invocation', () => {
   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);

package/bridge-plugins/helix.bridge.unreal/unreal/export_skeletal_mesh.py

@@ -15,6 +15,16 @@ UNREAL_OBJECT_PATH = re.compile(
     r"^/[A-Za-z0-9_+]+/(?:[A-Za-z0-9_+]+/)*[A-Za-z0-9_+]+(?:\.[A-Za-z0-9_+]+)?$"
 )
 
+# Mirrors bin/unreal-skeletal-mesh-extract.js's EXPORT_RESULTS_FILENAME/EXPORT_RESULTS_SCHEMA
+# (kept in sync by hand: this plugin script runs standalone inside UnrealEditor's Python VM,
+# not through the built CLI, so it cannot import that module). This is the per-asset results
+# manifest that lets a batch survive one bad asset: each job's outcome is recorded here so the
+# Node wrapper can tell "this asset really failed" apart from "the editor crashed before
+# writing anything", and still deliver every other asset's FBX/sidecar/textures as usable
+# output instead of discarding the whole batch (see batch-backlog.md item 13).
+EXPORT_RESULTS_SCHEMA = "helix.bridge.unreal-export-results/1"
+EXPORT_RESULTS_FILENAME = "_export-results.json"
+
 
 def required_environment(name: str) -> str:
     value = os.environ.get(name, "").strip()
@@ -288,8 +298,21 @@ def export_jobs():
     return jobs
 
 
+def write_export_results(output_dir: str, results) -> None:
+    payload = {
+        "schemaVersion": EXPORT_RESULTS_SCHEMA,
+        "results": results,
+    }
+    results_path = os.path.join(output_dir, EXPORT_RESULTS_FILENAME)
+    with open(results_path, "w", encoding="utf-8", newline="\n") as stream:
+        json.dump(payload, stream, indent=2, sort_keys=True, allow_nan=False)
+        stream.write("\n")
+
+
 def main() -> None:
     texture_cache = {}
+    results = []
+    output_dir = None
     for job in export_jobs():
         if not isinstance(job, dict):
             raise RuntimeError("Each Unreal export job must be an object")
@@ -306,12 +329,50 @@ def main() -> None:
             raise RuntimeError(
                 "Unreal export jobs require slug, assetPath, outputPath, and a boolean exportMorphTargets"
             )
-        export_asset({
+        if output_dir is None:
+            output_dir = os.path.dirname(output_path)
+
+        # A single bad asset (wrong type, won't load, corrupt material, ...) must not discard
+        # every other asset already queued in this batch commandlet run: catch it, record it,
+        # and move on. See batch-backlog.md item 13 — this used to propagate straight out of
+        # the loop and abort the whole UnrealEditor process, silently dropping every
+        # not-yet-processed asset even when they had nothing wrong with them.
+        try:
+            export_asset({
+                "slug": slug,
+                "assetPath": asset_path,
+                "outputPath": output_path,
+                "exportMorphTargets": export_morph_targets,
+            }, texture_cache)
+        except Exception as exc:
+            message = str(exc) or exc.__class__.__name__
+            unreal.log_error(
+                f"HELIX Bridge failed to export {asset_path!r} (slug {slug!r}); skipping it and "
+                f"continuing with the rest of the batch: {message}\n" + traceback.format_exc()
+            )
+            results.append({
+                "slug": slug,
+                "assetPath": asset_path,
+                "outputPath": output_path,
+                "status": "failed",
+                "error": message,
+            })
+            continue
+        results.append({
             "slug": slug,
             "assetPath": asset_path,
             "outputPath": output_path,
-            "exportMorphTargets": export_morph_targets,
-        }, texture_cache)
+            "status": "succeeded",
+        })
+
+    if output_dir is not None:
+        write_export_results(output_dir, results)
+
+    failed = [result for result in results if result["status"] == "failed"]
+    succeeded = [result for result in results if result["status"] == "succeeded"]
+    if failed and not succeeded:
+        summary = "; ".join(f"{result['slug']}: {result['error']}" for result in failed)
+        raise RuntimeError(f"Every asset in this batch failed to export ({summary})")
 
 
 try:

package/bridge-recipes/unreal/helix-character-creator-male/male-carnival-mask-2.addon.json

@@ -0,0 +1 @@
+{"schemaVersion": "helix.bridge-character-addon-profile/1", "title": "Carnival Mask 2", "slug": "male-carnival-mask-2", "hostItemId": "b45e4a1e-0000-4000-8000-000000000001", "hostSha256": "3fdb769bf0dbcc0e1b1b1ae8dd800d6ddedfda976c6422d4de15b80ce71c132b", "slotType": "character.mask@1", "socket": "head", "nodes": [], "ops": []}

package/bridge-recipes/unreal/helix-character-creator-male/male-carnival-mask-2.json

@@ -0,0 +1 @@
+{"schemaVersion": "helix.bridge.unreal-asset/1", "slug": "male-carnival-mask-2", "assetPath": "/HelixCharacterCreator/Characters/Clothes/Man/M_Carnival_Mask_2/M_Carnival_Mask_2", "exportMorphTargets": true}

package/bridge-recipes/unreal/helix-character-creator-male/male-carnival-mask-3.addon.json

@@ -0,0 +1 @@
+{"schemaVersion": "helix.bridge-character-addon-profile/1", "title": "Carnival Mask 3", "slug": "male-carnival-mask-3", "hostItemId": "b45e4a1e-0000-4000-8000-000000000001", "hostSha256": "3fdb769bf0dbcc0e1b1b1ae8dd800d6ddedfda976c6422d4de15b80ce71c132b", "slotType": "character.mask@1", "socket": "head", "nodes": [], "ops": []}

package/bridge-recipes/unreal/helix-character-creator-male/male-carnival-mask-3.json

@@ -0,0 +1 @@
+{"schemaVersion": "helix.bridge.unreal-asset/1", "slug": "male-carnival-mask-3", "assetPath": "/HelixCharacterCreator/Characters/Clothes/Man/M_Carnival_Mask_3/M_Carnival_Mask_3", "exportMorphTargets": true}

package/bridge-recipes/unreal/helix-character-creator-male/male-eye-hole-mask-2.addon.json

@@ -0,0 +1 @@
+{"schemaVersion": "helix.bridge-character-addon-profile/1", "title": "Eye Hole Mask 2", "slug": "male-eye-hole-mask-2", "hostItemId": "b45e4a1e-0000-4000-8000-000000000001", "hostSha256": "3fdb769bf0dbcc0e1b1b1ae8dd800d6ddedfda976c6422d4de15b80ce71c132b", "slotType": "character.mask@1", "socket": "head", "nodes": [], "ops": []}

package/bridge-recipes/unreal/helix-character-creator-male/male-eye-hole-mask-2.json

@@ -0,0 +1 @@
+{"schemaVersion": "helix.bridge.unreal-asset/1", "slug": "male-eye-hole-mask-2", "assetPath": "/HelixCharacterCreator/Characters/Clothes/Man/M_Eye_Hole_Mask_2/M_Eye_Hole_Mask_2_skinning", "exportMorphTargets": true}

package/bridge-recipes/unreal/helix-character-creator-male/male-eye-hole-mask.addon.json

@@ -0,0 +1 @@
+{"schemaVersion": "helix.bridge-character-addon-profile/1", "title": "Eye Hole Mask", "slug": "male-eye-hole-mask", "hostItemId": "b45e4a1e-0000-4000-8000-000000000001", "hostSha256": "3fdb769bf0dbcc0e1b1b1ae8dd800d6ddedfda976c6422d4de15b80ce71c132b", "slotType": "character.mask@1", "socket": "head", "nodes": [], "ops": []}

package/bridge-recipes/unreal/helix-character-creator-male/male-eye-hole-mask.json

@@ -0,0 +1 @@
+{"schemaVersion": "helix.bridge.unreal-asset/1", "slug": "male-eye-hole-mask", "assetPath": "/HelixCharacterCreator/Characters/Clothes/Man/M_Eye_Hole_Mask/M_Eye_Hole_Mask_skinning", "exportMorphTargets": true}

package/bridge-recipes/unreal/helix-character-creator-male/male-marshmallow-mask.addon.json

@@ -0,0 +1 @@
+{"schemaVersion": "helix.bridge-character-addon-profile/1", "title": "Marshmallow Mask", "slug": "male-marshmallow-mask", "hostItemId": "b45e4a1e-0000-4000-8000-000000000001", "hostSha256": "3fdb769bf0dbcc0e1b1b1ae8dd800d6ddedfda976c6422d4de15b80ce71c132b", "slotType": "character.mask@1", "socket": "head", "nodes": [], "ops": []}

package/bridge-recipes/unreal/helix-character-creator-male/male-marshmallow-mask.json

@@ -0,0 +1 @@
+{"schemaVersion": "helix.bridge.unreal-asset/1", "slug": "male-marshmallow-mask", "assetPath": "/HelixCharacterCreator/Characters/Clothes/Man/Marshmallow_Mask/M_Marshmallow_Mask", "exportMorphTargets": true}

package/bridge-recipes/unreal/helix-character-creator-male/male-nebula-executive-coat.addon.json

@@ -0,0 +1 @@
+{"schemaVersion": "helix.bridge-character-addon-profile/1", "title": "Nebula Executive Coat", "slug": "male-nebula-executive-coat", "hostItemId": "b45e4a1e-0000-4000-8000-000000000001", "hostSha256": "3fdb769bf0dbcc0e1b1b1ae8dd800d6ddedfda976c6422d4de15b80ce71c132b", "slotType": "character.top@1", "socket": "chest", "nodes": [], "ops": []}

package/bridge-recipes/unreal/helix-character-creator-male/male-nebula-executive-coat.json

@@ -0,0 +1 @@
+{"schemaVersion": "helix.bridge.unreal-asset/1", "slug": "male-nebula-executive-coat", "assetPath": "/HelixCharacterCreator/Characters/Clothes/Man/Nebula_Executive_Coat/SKM_M_Nebula_Executive_West_Coat", "exportMorphTargets": true}

package/bridge-recipes/unreal/helix-character-creator-male/male-neo-arcane-heir-mantle.addon.json

@@ -0,0 +1 @@
+{"schemaVersion": "helix.bridge-character-addon-profile/1", "title": "NEO Arcane Heir Mantle", "slug": "male-neo-arcane-heir-mantle", "hostItemId": "b45e4a1e-0000-4000-8000-000000000001", "hostSha256": "3fdb769bf0dbcc0e1b1b1ae8dd800d6ddedfda976c6422d4de15b80ce71c132b", "slotType": "character.top@1", "socket": "chest", "nodes": [], "ops": []}

package/bridge-recipes/unreal/helix-character-creator-male/male-neo-arcane-heir-mantle.json

@@ -0,0 +1 @@
+{"schemaVersion": "helix.bridge.unreal-asset/1", "slug": "male-neo-arcane-heir-mantle", "assetPath": "/HelixCharacterCreator/Characters/Clothes/Man/NEO_Arcane_Heir_Mantle/SKM_M_NEO_Arcane_Heir_Mantle", "exportMorphTargets": true}

package/bridge-recipes/unreal/helix-character-creator-male/male-neo-arcane-heir-tunic.addon.json

@@ -0,0 +1 @@
+{"schemaVersion": "helix.bridge-character-addon-profile/1", "title": "NEO Arcane Heir Tunic", "slug": "male-neo-arcane-heir-tunic", "hostItemId": "b45e4a1e-0000-4000-8000-000000000001", "hostSha256": "3fdb769bf0dbcc0e1b1b1ae8dd800d6ddedfda976c6422d4de15b80ce71c132b", "slotType": "character.top@1", "socket": "chest", "nodes": [], "ops": []}

package/bridge-recipes/unreal/helix-character-creator-male/male-neo-arcane-heir-tunic.json

@@ -0,0 +1 @@
+{"schemaVersion": "helix.bridge.unreal-asset/1", "slug": "male-neo-arcane-heir-tunic", "assetPath": "/HelixCharacterCreator/Characters/Clothes/Man/NEO_Arcane_Heir_Tunic/SKM_M_NEO_Arcane_Heir_Tunic", "exportMorphTargets": true}

package/bridge-recipes/unreal/helix-character-creator-male/male-paper-bag-mask.addon.json

@@ -0,0 +1 @@
+{"schemaVersion": "helix.bridge-character-addon-profile/1", "title": "Paper Bag Mask", "slug": "male-paper-bag-mask", "hostItemId": "b45e4a1e-0000-4000-8000-000000000001", "hostSha256": "3fdb769bf0dbcc0e1b1b1ae8dd800d6ddedfda976c6422d4de15b80ce71c132b", "slotType": "character.mask@1", "socket": "head", "nodes": [], "ops": []}

package/bridge-recipes/unreal/helix-character-creator-male/male-paper-bag-mask.json

@@ -0,0 +1 @@
+{"schemaVersion": "helix.bridge.unreal-asset/1", "slug": "male-paper-bag-mask", "assetPath": "/HelixCharacterCreator/Characters/Clothes/Man/M_Paper_Bag_Mask/M_Paper_Bag_Mask", "exportMorphTargets": true}

package/bridge-recipes/unreal/helix-character-creator-male/male-pig-mask.addon.json

@@ -0,0 +1 @@
+{"schemaVersion": "helix.bridge-character-addon-profile/1", "title": "Pig Mask", "slug": "male-pig-mask", "hostItemId": "b45e4a1e-0000-4000-8000-000000000001", "hostSha256": "3fdb769bf0dbcc0e1b1b1ae8dd800d6ddedfda976c6422d4de15b80ce71c132b", "slotType": "character.mask@1", "socket": "head", "nodes": [], "ops": []}

package/bridge-recipes/unreal/helix-character-creator-male/male-pig-mask.json

@@ -0,0 +1 @@
+{"schemaVersion": "helix.bridge.unreal-asset/1", "slug": "male-pig-mask", "assetPath": "/HelixCharacterCreator/Characters/Clothes/Man/M_Pig_Mask/M_Pig_Mask", "exportMorphTargets": true}

package/bridge-recipes/unreal/helix-character-creator-male/male-puffer-jacket.addon.json

@@ -0,0 +1 @@
+{"schemaVersion": "helix.bridge-character-addon-profile/1", "title": "Puffer Jacket", "slug": "male-puffer-jacket", "hostItemId": "b45e4a1e-0000-4000-8000-000000000001", "hostSha256": "3fdb769bf0dbcc0e1b1b1ae8dd800d6ddedfda976c6422d4de15b80ce71c132b", "slotType": "character.top@1", "socket": "chest", "nodes": [], "ops": []}

package/bridge-recipes/unreal/helix-character-creator-male/male-puffer-jacket.json

@@ -0,0 +1 @@
+{"schemaVersion": "helix.bridge.unreal-asset/1", "slug": "male-puffer-jacket", "assetPath": "/HelixCharacterCreator/Characters/Clothes/Man/Puffer_Jacket/SKM_M_Puffer_Jacket", "exportMorphTargets": true}

package/bridge-recipes/unreal/helix-character-creator-male/male-pullover-hoodie.addon.json

@@ -0,0 +1 @@
+{"schemaVersion": "helix.bridge-character-addon-profile/1", "title": "Pullover Hoodie", "slug": "male-pullover-hoodie", "hostItemId": "b45e4a1e-0000-4000-8000-000000000001", "hostSha256": "3fdb769bf0dbcc0e1b1b1ae8dd800d6ddedfda976c6422d4de15b80ce71c132b", "slotType": "character.top@1", "socket": "chest", "nodes": [], "ops": []}

package/bridge-recipes/unreal/helix-character-creator-male/male-pullover-hoodie.json

@@ -0,0 +1 @@
+{"schemaVersion": "helix.bridge.unreal-asset/1", "slug": "male-pullover-hoodie", "assetPath": "/HelixCharacterCreator/Characters/Clothes/Man/Pullover_Hoodie/SKM_M_Pullover_Hoodie", "exportMorphTargets": true}

package/bridge-recipes/unreal/helix-character-creator-male/male-sinth-ascetic-jacket.addon.json

@@ -0,0 +1 @@
+{"schemaVersion": "helix.bridge-character-addon-profile/1", "title": "Sinth Ascetic Jacket", "slug": "male-sinth-ascetic-jacket", "hostItemId": "b45e4a1e-0000-4000-8000-000000000001", "hostSha256": "3fdb769bf0dbcc0e1b1b1ae8dd800d6ddedfda976c6422d4de15b80ce71c132b", "slotType": "character.top@1", "socket": "chest", "nodes": [], "ops": []}

package/bridge-recipes/unreal/helix-character-creator-male/male-sinth-ascetic-jacket.json

@@ -0,0 +1 @@
+{"schemaVersion": "helix.bridge.unreal-asset/1", "slug": "male-sinth-ascetic-jacket", "assetPath": "/HelixCharacterCreator/Characters/Clothes/Man/Sinth_Ascetic_Jacket/SKM_M_Sinth_Ascetic_Jacket", "exportMorphTargets": true}

package/bridge-recipes/unreal/helix-character-creator-male/male-surgeon-mask.addon.json

@@ -0,0 +1 @@
+{"schemaVersion": "helix.bridge-character-addon-profile/1", "title": "Surgeon Mask", "slug": "male-surgeon-mask", "hostItemId": "b45e4a1e-0000-4000-8000-000000000001", "hostSha256": "3fdb769bf0dbcc0e1b1b1ae8dd800d6ddedfda976c6422d4de15b80ce71c132b", "slotType": "character.mask@1", "socket": "head", "nodes": [], "ops": []}

package/bridge-recipes/unreal/helix-character-creator-male/male-surgeon-mask.json

@@ -0,0 +1 @@
+{"schemaVersion": "helix.bridge.unreal-asset/1", "slug": "male-surgeon-mask", "assetPath": "/HelixCharacterCreator/Characters/Clothes/Man/M_Surgeon_Mask/M_Surgeon_Mask_skinning", "exportMorphTargets": true}

package/bridge-recipes/unreal/helix-character-creator-male/male-tech-hoodie.addon.json

@@ -0,0 +1 @@
+{"schemaVersion": "helix.bridge-character-addon-profile/1", "title": "Tech Hoodie", "slug": "male-tech-hoodie", "hostItemId": "b45e4a1e-0000-4000-8000-000000000001", "hostSha256": "3fdb769bf0dbcc0e1b1b1ae8dd800d6ddedfda976c6422d4de15b80ce71c132b", "slotType": "character.top@1", "socket": "chest", "nodes": [], "ops": []}

package/bridge-recipes/unreal/helix-character-creator-male/male-tech-hoodie.json

@@ -0,0 +1 @@
+{"schemaVersion": "helix.bridge.unreal-asset/1", "slug": "male-tech-hoodie", "assetPath": "/HelixCharacterCreator/Characters/Clothes/Man/Tech_Hoodie/SKM_M_Tech_Hoodie", "exportMorphTargets": true}

package/bridge-recipes/unreal/helix-character-creator-male/test/recipes.test.js

@@ -8,15 +8,28 @@ const test = require('node:test');
 const directory = resolve(__dirname, '..');
 const hostItemId = 'b45e4a1e-0000-4000-8000-000000000001';
 
+// The fixed, one-representative-item-per-customizer-slot pilot set that
+// `all.json` is a canonical batch of. This list is intentionally NOT derived
+// from a directory scan: the batch phase adds many more `<item-slug>.json` /
+// `<item-slug>.addon.json` recipe pairs to this same directory (one per
+// wearable, not one per slot), and those must coexist without being folded
+// into — or breaking the identity check against — this specific pilot batch.
+const canonicalSlotFiles = [
+  'base-male.json',
+  'base-male-face.json',
+  'back.json', 'bottom.json', 'eyewear.json', 'footwear.json', 'gloves.json',
+  'hair.json', 'headwear.json', 'mask.json', 'neck.json', 'outfit.json', 'top.json',
+];
+const canonicalSlots = [
+  'back', 'bottom', 'eyewear', 'footwear', 'gloves', 'hair', 'headwear', 'mask', 'neck', 'outfit', 'top',
+];
+
 function read(file) {
   return JSON.parse(readFileSync(join(directory, file), 'utf8'));
 }
 
 test('keeps the canonical batch identical to its individual source profiles', () => {
-  const files = readdirSync(directory)
-    .filter((file) => file.endsWith('.json') && !['all.json', 'palette-pilot.json'].includes(file) && !file.endsWith('.addon.json'))
-    .sort();
-  const profiles = files.map(read);
+  const profiles = canonicalSlotFiles.map(read);
   const batch = read('all.json');
   assert.equal(batch.schemaVersion, 'helix.bridge.unreal-asset-set/1');
   assert.deepEqual(
@@ -26,11 +39,19 @@ test('keeps the canonical batch identical to its individual source profiles', ()
   assert.equal(new Set(batch.assets.map((asset) => asset.slug)).size, batch.assets.length);
 });
 
-test('pairs every wearable source with a runtime customizer add-on profile', () => {
+test('every add-on profile in this directory pairs with a runtime customizer add-on profile of matching shape', () => {
+  // Covers every `.addon.json` file present — the fixed 11-slot pilot set AND
+  // any number of additional per-item batch-phase recipes — rather than a
+  // closed exact-list. A new wearable's recipe pair must satisfy the same
+  // schema contract as the originals; it does not need to be one of the 11
+  // canonical slot names, and there may be many per slot.
   const addonFiles = readdirSync(directory).filter((file) => file.endsWith('.addon.json')).sort();
-  assert.deepEqual(addonFiles.map((file) => basename(file, '.addon.json')), [
-    'back', 'bottom', 'eyewear', 'footwear', 'gloves', 'hair', 'headwear', 'mask', 'neck', 'outfit', 'top',
-  ]);
+  // The 11 canonical per-slot pilot add-ons must still exist under their
+  // original slot-named files.
+  for (const slot of canonicalSlots) {
+    assert.ok(addonFiles.includes(`${slot}.addon.json`), `missing canonical ${slot}.addon.json`);
+  }
+  const seenSlugs = new Set();
   for (const file of addonFiles) {
     const addon = read(file);
     const source = read(`${basename(file, '.addon.json')}.json`);
@@ -39,6 +60,8 @@ test('pairs every wearable source with a runtime customizer add-on profile', ()
     assert.equal(addon.hostItemId, hostItemId);
     assert.match(addon.slotType, /^character\.[a-z]+@1$/);
     assert.equal(addon.slotType.startsWith('Cosmetic.Slot.'), false);
+    assert.equal(seenSlugs.has(addon.slug), false, `duplicate add-on slug ${addon.slug} (${file})`);
+    seenSlugs.add(addon.slug);
   }
 });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@helix3/helix-cli",
-  "version": "0.1.18-helix3.273",
+  "version": "0.1.18-helix3.275",
   "description": "helix — the HELIX creator CLI: scaffold, validate, and publish Instant Worlds",
   "main": "dist/lib.js",
   "types": "dist/lib.d.ts",