@helix3/helix-cli 0.1.14-helix3.180 → 0.1.14-helix3.182

package/docs/bridge.md

@@ -43,6 +43,7 @@ Blocked `bridge plan` and `bridge import --dry-run` commands print the complete
 | Unity project | `Assets/` + project settings | plan seam; install a batch-mode adapter | canonical GLB → Scene v2 |
 | Godot project | `project.godot` | plan seam; install a headless adapter | canonical GLB → Scene v2 |
 | MetaHuman face GLB | `FaceMesh` + baked-eye material names | head bake, canonical eye bake, material repair | web face GLB |
+| Unpacked BeamNG vehicle mod | `vehicles/` marker through `hypersonic.beamng-vehicle` | default JBeam configuration, source DAE/PBR/audio evidence, canonical vehicle receipt, fail-closed acceptance | canonical textured GLB |
 
 Modular character parts use `--type addon --input host=<base-avatar.glb> --input addon=<profile.json>`. The profile must carry `hostSha256` for that exact host GLB and the runtime `character.<slot>@1` fitment contract used by the customizer. Bridge validates the host as a base avatar, hashes it, rejects a digest mismatch, and runs the generated `fits` and `ops` through the same exact runtime contract validator used by Universal Item publishing. Upload-only `Cosmetic.Slot.*` values, undeclared nodes/paths/pointers, and unsupported operations are rejected before an add-on package is published.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@helix3/helix-cli",
-  "version": "0.1.14-helix3.180",
+  "version": "0.1.14-helix3.182",
   "description": "helix — the HELIX creator CLI: scaffold, validate, and publish Instant Worlds",
   "main": "dist/lib.js",
   "types": "dist/lib.d.ts",
@@ -45,6 +45,7 @@
     "bridge-recipes",
     "docs/bridge.md",
     "dist",
+    "plugins/beamng-vehicle",
     "vendor"
   ],
   "scripts": {
@@ -61,7 +62,7 @@
     "@gltf-transform/extensions": "^4.4.0",
     "@gltf-transform/functions": "^4.4.0",
     "@hypersoniclabs/helix-manifest": "npm:@helix3/helix-manifest@0.3.22-helix3.62",
-    "@hypersoniclabs/helix-sdk": "npm:@helix3/helix-sdk@0.1.5-helix3.93",
+    "@hypersoniclabs/helix-sdk": "npm:@helix3/helix-sdk@0.1.5-helix3.95",
     "commander": "^13.0.0",
     "ktx2-encoder": "^0.5.3",
     "meshoptimizer": "^0.22.0",

package/plugins/beamng-vehicle/README.md

@@ -0,0 +1,21 @@
+# BeamNG Vehicle Bridge Plugin
+
+This plugin makes `helix bridge import <unpacked-mod>` the single preflight and conversion path for BeamNG road vehicles. It deliberately refuses a source rather than publishing a car that only looks complete in a file listing.
+
+The importer performs two gates:
+
+1. Candidate assessment selects exactly one `vehicles/<id>` root and requires JBeam, render geometry, source material bindings, an authored steering-wheel mesh, real cabin signals, rims **and authored tyre geometry**, four wheel signals, and recorded or source-referenced engine audio. JBeam power-steering text cannot satisfy the visual steering requirement, and a rim radius cannot satisfy the tyre requirement.
+2. Conversion runs Blender headlessly, binds source materials and textures, derives the canonical HELIX receipt and internal source provenance, and then acceptance-tests dimensions, triangle budget, `+Z` forward semantics, wheel and tyre geometry, measured engine placement, authored seat H-points and steering geometry, cockpit ergonomics, texture coverage, provenance, and audio evidence. Repairs remain recorded but cannot manufacture source eligibility. A rear-at-`+Z` export is converted again with a geometry-only front/back reflection; any other failed check blocks the import.
+
+BeamNG vehicle archives commonly reference tyres shipped by the base game instead of duplicating them in every mod. Point `HELIX_BEAMNG_COMMON_ROOT` at an unpacked, locally available BeamNG common-asset root before planning/importing such a vehicle. The selected dependency is recorded in the import report; if neither the archive nor that root contains authored tyre geometry, candidate assessment refuses the vehicle instead of publishing bare rims.
+
+Local development:
+
+```bash
+npm run build
+node dist/index.js bridge plugins inspect plugins/beamng-vehicle --json
+node dist/index.js bridge plugins test plugins/beamng-vehicle --json
+node dist/index.js bridge plan /path/to/unpacked-mod --plugin-dir plugins/beamng-vehicle --plugin hypersonic.beamng-vehicle --json
+```
+
+External-plugin execution still requires the Bridge plan key and all permissions named by the reviewed plan. The plugin does not weaken Bridge's immutable source snapshot or provenance rules.

package/plugins/beamng-vehicle/bin/beamng-vehicle.mjs

@@ -0,0 +1,279 @@
+#!/usr/bin/env node
+import { spawn } from 'node:child_process';
+import { copyFileSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import { basename, dirname, extname, join, relative, resolve } from 'node:path';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+import { auditVehicleGlb, injectVehicleReceipt } from '../lib/vehicle-qa.mjs';
+
+const MAX_FILES = 50_000;
+const MAX_DAE = 12;
+const MAX_CONVERTER_LOG_BYTES = 1024 * 1024;
+const AUDIO_EXTENSIONS = new Set(['.wav', '.ogg', '.flac', '.mp3']);
+
+function walk(root) {
+  const rows = [];
+  const visit = (dir) => {
+    for (const entry of readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+      const path = join(dir, entry.name);
+      if (entry.isSymbolicLink()) throw new Error(`source contains a symlink: ${relative(root, path)}`);
+      if (entry.isDirectory()) visit(path);
+      else if (entry.isFile()) rows.push(path);
+      if (rows.length > MAX_FILES) throw new Error(`source contains more than ${MAX_FILES} files`);
+    }
+  };
+  visit(root);
+  return rows;
+}
+
+function semanticCount(files, pattern) {
+  return files.reduce((count, path) => count + (pattern.test(basename(path).toLowerCase()) ? 1 : 0), 0);
+}
+
+function sourceReferencesAudio(jbeams) {
+  return jbeams.some((path) => /soundconfig|sampleName|engineSound|exhaustSound/i.test(readFileSync(path, 'utf8')));
+}
+
+function daeHasAuthoredSteering(path) {
+  return /(?:id|name)="[^"]*steer(?:ing)?(?:wheel|rim)?[^"]*"/i.test(readFileSync(path, 'utf8'));
+}
+
+function daeHasAuthoredTyre(path) {
+  return /(?:id|name)="[^"]*(?:tyre|tire)[^"]*"/i.test(readFileSync(path, 'utf8'));
+}
+
+function commonTyreDependency() {
+  const configured = process.env.HELIX_BEAMNG_COMMON_ROOT;
+  if (!configured || !existsSync(configured)) return null;
+  const candidates = walk(resolve(configured)).filter((path) => extname(path).toLowerCase() === '.dae'
+    && /(?:tyre|tire)/i.test(basename(path)) && daeHasAuthoredTyre(path));
+  return candidates.sort((a, b) => lstatSync(b).size - lstatSync(a).size || a.localeCompare(b))[0] ?? null;
+}
+
+function dependencyReceipt(path) {
+  if (!path) return null;
+  const configured = process.env.HELIX_BEAMNG_COMMON_ROOT;
+  if (!configured) return basename(path);
+  return relative(resolve(configured), path);
+}
+
+function assess(source) {
+  const vehicles = join(source, 'vehicles');
+  if (!existsSync(vehicles)) throw new Error("not a BeamNG mod: missing top-level 'vehicles' directory");
+  const tyreDependency = commonTyreDependency();
+  const candidates = readdirSync(vehicles, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory() && entry.name !== 'common')
+    .map((entry) => {
+      const root = join(vehicles, entry.name);
+      const files = walk(root);
+      const jbeams = files.filter((path) => extname(path).toLowerCase() === '.jbeam');
+      const daes = files.filter((path) => extname(path).toLowerCase() === '.dae');
+      const glbs = files.filter((path) => extname(path).toLowerCase() === '.glb');
+      const materials = files.filter((path) => /(?:\.materials\.json|materials\.cs)$/i.test(path));
+      const audio = files.filter((path) => AUDIO_EXTENSIONS.has(extname(path).toLowerCase()));
+      const cabin = semanticCount(files, /(interior|cabin|dashboard|dash|seat|steer)/)
+        + Math.min(20, jbeams.reduce((count, path) => count + (readFileSync(path, 'utf8').match(/seat|steer|dashboard|interior|cabin/gi)?.length ?? 0), 0));
+      const wheels = semanticCount(files, /(wheel|rim|tyre|tire)/)
+        + Math.min(12, jbeams.reduce((count, path) => count + (readFileSync(path, 'utf8').match(/wheel|rim|tyre|tire/gi)?.length ?? 0), 0));
+      const audioReferences = sourceReferencesAudio(jbeams);
+      const hasAudio = audio.length > 0 || audioReferences;
+      // JBeam power-steering controllers are not visual cabin evidence. Require
+      // a steering object in DAE geometry before spending a Blender conversion.
+      // Source GLBs are checked for the same authorship receipt after conversion.
+      const authoredSteering = glbs.length > 0 || daes.some(daeHasAuthoredSteering);
+      const authoredTyres = glbs.length > 0 || daes.some(daeHasAuthoredTyre) || tyreDependency !== null;
+      const blockers = [];
+      if (jbeams.length === 0) blockers.push('no JBeam vehicle definition');
+      if (jbeams.length > 0 && jbeams.length < 5) blockers.push('fewer than five configurable JBeam part definitions');
+      if (daes.length === 0 && glbs.length === 0) blockers.push('no DAE or GLB render geometry');
+      if (materials.length === 0) blockers.push('no BeamNG material bindings');
+      if (cabin < 2) blockers.push('no convincing cabin/steering source');
+      if (!authoredSteering) blockers.push('no authored steering-wheel mesh in source geometry');
+      if (!authoredTyres) blockers.push('no authored tyre geometry in the mod or HELIX_BEAMNG_COMMON_ROOT');
+      if (wheels < 4) blockers.push('fewer than four wheel/rim/tyre source signals');
+      if (!hasAudio) blockers.push('no recorded audio and no source engine/exhaust sound reference');
+      const score = jbeams.length * 2 + Math.min(daes.length + glbs.length, 12) * 3
+        + Math.min(materials.length, 8) * 2 + Math.min(cabin, 20) + Math.min(wheels, 12) + (hasAudio ? 10 : 0);
+      return { id: entry.name, root, files, jbeams, daes, glbs, materials, audio, audioReferences,
+        cabin, wheels, hasAudio, authoredSteering, authoredTyres, tyreDependency, blockers, score };
+    });
+  const viable = candidates.filter((row) => row.blockers.length === 0).sort((a, b) => b.score - a.score || a.id.localeCompare(b.id));
+  if (viable.length === 0) {
+    throw new Error(`no importable BeamNG vehicle:\n${candidates.map((row) => `- ${row.id}: ${row.blockers.join('; ')}`).join('\n')}`);
+  }
+  if (viable.length > 1 && viable[0].score === viable[1].score) {
+    throw new Error(`ambiguous BeamNG mod: equally viable vehicles ${viable.filter((row) => row.score === viable[0].score).map((row) => row.id).join(', ')}`);
+  }
+  return { selected: viable[0], candidates };
+}
+
+function blenderExecutable() {
+  const candidates = [process.env.HELIX_BLENDER, '/Applications/Blender.app/Contents/MacOS/Blender', 'blender'].filter(Boolean);
+  return candidates.find((candidate) => candidate.includes('/') ? existsSync(candidate) : true);
+}
+
+function run(executable, args) {
+  return new Promise((ok, fail) => {
+    const child = spawn(executable, args, { stdio: ['ignore', 'pipe', 'pipe'], shell: false });
+    let stdout = '', stderr = '';
+    const tail = (current, chunk) => `${current}${chunk.toString('utf8')}`.slice(-MAX_CONVERTER_LOG_BYTES);
+    child.stdout.on('data', (chunk) => { stdout = tail(stdout, chunk); });
+    child.stderr.on('data', (chunk) => { stderr = tail(stderr, chunk); });
+    child.on('error', fail);
+    child.on('close', (code) => code === 0 ? ok(`${stdout}\n${stderr}`)
+      : fail(new Error(`${basename(executable)} exited ${code}: ${stderr.slice(-4000)}`)));
+  });
+}
+
+function requestedConfiguration(source, candidate) {
+  const hint = basename(source).toLowerCase().replace(/[^a-z0-9]+/g, '');
+  const matches = candidate.files.filter((path) => /^info(?:_[^.]+)?\.json$/i.test(basename(path))).flatMap((path) => {
+    try {
+      const info = JSON.parse(readFileSync(path, 'utf8'));
+      const id = basename(path).match(/^info_([^.]+)\.json$/i)?.[1] ?? '';
+      const tokens = `${String(info.Configuration ?? info.configuration ?? '')} ${id}`.toLowerCase().match(/[a-z0-9]+/g) ?? [];
+      const token = tokens.filter((value) => value.length >= 3 && hint.includes(value))
+        .sort((a, b) => b.length - a.length || a.localeCompare(b))[0];
+      return token ? [{ configuration: token, year: Number(info.Years?.max ?? info.years?.max ?? 0), specificity: token.length }] : [];
+    } catch { return []; }
+  }).sort((a, b) => b.specificity - a.specificity || b.year - a.year || a.configuration.localeCompare(b.configuration));
+  return matches[0]?.configuration || null;
+}
+
+function compatibilityProfile(candidate, configurationHint) {
+  const path = resolve(dirname(fileURLToPath(import.meta.url)), '..', 'profiles', 'source-compatibility.json');
+  const profiles = JSON.parse(readFileSync(path, 'utf8')).profiles ?? [];
+  return profiles.find((profile) => profile.candidateId === candidate.id
+    && (profile.configuration ?? null) === configurationHint) ?? null;
+}
+
+function daeSelection(candidate, configurationHint = null) {
+  const own = candidate.daes.sort((a, b) => {
+    const identity = Number(basename(a, '.dae').toLowerCase() === candidate.id.toLowerCase())
+      - Number(basename(b, '.dae').toLowerCase() === candidate.id.toLowerCase());
+    return identity || lstatSync(b).size - lstatSync(a).size;
+  });
+  // BeamNG mods commonly carry complete trim/configuration variants as separate large DAEs.
+  // Combining them creates several cars in one GLB, so import exactly one highest-confidence
+  // primary body plus only small, explicitly named wheel geometry.
+  const rootLevel = own.filter((path) => dirname(path) === candidate.root);
+  let primary = rootLevel[0] ?? own[0];
+  const requestedBadge = configurationHint;
+  if (requestedBadge) {
+    const variants = candidate.files.filter((path) => /^info(?:_[^.]+)?\.json$/i.test(basename(path))).flatMap((path) => {
+      try {
+        const info = JSON.parse(readFileSync(path, 'utf8'));
+        const configuration = String(info.Configuration ?? info.configuration ?? '').toLowerCase().replace(/[^a-z0-9]/g, '');
+        const id = basename(path).match(/^info_([^.]+)\.json$/i)?.[1];
+        const year = Number(info.Years?.max ?? info.years?.max ?? 0);
+        return id && configuration.includes(requestedBadge) ? [{ id, year }] : [];
+      } catch { return []; }
+    }).sort((a, b) => b.year - a.year || a.id.localeCompare(b.id));
+    const selected = variants[0] && own.find((path) => path.split('/').includes(variants[0].id));
+    if (selected) primary = selected;
+  }
+  const normalized = (path) => path.toLowerCase().replace(/[^a-z0-9]+/g, '');
+  const desired = requestedBadge
+    ? own.filter((path) => normalized(relative(candidate.root, path)).includes(requestedBadge)) : [];
+  const desiredBody = desired.filter((path) => !/(wheel|rim|tyre|tire|steer)/i.test(path))
+    .sort((a, b) => lstatSync(b).size - lstatSync(a).size)[0];
+  const desiredSteering = desired.filter((path) => /steer/i.test(path))
+    .sort((a, b) => lstatSync(b).size - lstatSync(a).size)[0];
+  const desiredWheels = desired.filter((path) => /(wheel|rim|tyre|tire)/i.test(path))
+    .sort((a, b) => lstatSync(b).size - lstatSync(a).size).slice(0, 2);
+  const profile = compatibilityProfile(candidate, configurationHint);
+  const supplemental = (profile?.supplementalGeometry ?? []).flatMap((rule) => own.filter((path) => {
+    const relativePath = normalized(relative(candidate.root, path));
+    return (rule.include ?? []).every((token) => relativePath.includes(token))
+      && !(rule.exclude ?? []).some((token) => relativePath.includes(token));
+  }).sort((a, b) => lstatSync(b).size - lstatSync(a).size).slice(0, 1));
+  const suspension = rootLevel.find((path) => /suspension/i.test(path));
+  const pedals = own.find((path) => /pedal/i.test(path));
+  const shared = own.filter((path) => !desired.includes(path) && path !== primary
+    && /(wheel|rim|tyre|tire)/i.test(path) && lstatSync(path).size < 25 * 1024 * 1024);
+  return [...new Set([primary, suspension, desiredBody, ...supplemental, desiredSteering, ...desiredWheels, pedals,
+    candidate.tyreDependency,
+    ...shared.slice(0, desiredWheels.length > 0 ? 0 : 3)].filter(Boolean))].slice(0, MAX_DAE);
+}
+
+function stampBridgeProvenance(output, source, selected) {
+  injectVehicleReceipt(output, {
+    HELIX_provenance: {
+      source: `BeamNG vehicle mod ${basename(source)} / vehicles/${selected.id}`,
+      derivation: 'mod-derived',
+      distribution: 'INTERNAL-ONLY',
+      convertedBy: 'HELIX Bridge / hypersonic.beamng-vehicle',
+      convertedOn: new Date().toISOString().slice(0, 10),
+      pipeline: 'BeamNG candidate assessment + authored geometry/material conversion + canonical vehicle QA',
+    },
+  });
+}
+
+async function convert(source, candidate, output, mirrorZ = false) {
+  if (candidate.glbs.length > 0) {
+    const preferred = candidate.glbs.sort((a, b) => lstatSync(b).size - lstatSync(a).size)[0];
+    copyFileSync(preferred, output);
+    return { converter: 'source-glb', sourceGeometry: [relative(candidate.root, preferred)] };
+  }
+  const blender = blenderExecutable();
+  if (!blender) throw new Error('Blender is required to convert BeamNG DAE geometry');
+  const configurationHint = requestedConfiguration(source, candidate);
+  const daes = daeSelection(candidate, configurationHint);
+  if (daes.length === 0) throw new Error('candidate has no DAE geometry after selection');
+  const receipt = `${output}.receipt.json`;
+  const pluginDir = dirname(fileURLToPath(import.meta.url));
+  const args = ['-b', '--python', resolve(pluginDir, 'convert-beamng.py'), '--',
+    '--source-root', source, '--vehicle-root', candidate.root, '--output', output, '--receipt', receipt,
+    ...daes.flatMap((path) => ['--dae', path]),
+    ...(candidate.tyreDependency ? ['--material-root', resolve(process.env.HELIX_BEAMNG_COMMON_ROOT)] : []),
+    ...(configurationHint ? ['--configuration-hint', configurationHint] : []),
+    ...(mirrorZ ? ['--mirror-z'] : [])];
+  const converterLog = await run(blender, args);
+  if (!existsSync(receipt)) {
+    throw new Error(`Blender did not produce a vehicle receipt:\n${converterLog.slice(-6000)}`);
+  }
+  injectVehicleReceipt(output, JSON.parse(readFileSync(receipt, 'utf8')));
+  return { converter: 'blender-dae', sourceGeometry: daes.map((path) => path === candidate.tyreDependency
+    ? `common-dependency:${dependencyReceipt(path)}` : relative(candidate.root, path)),
+    configurationHint, mirrorZ };
+}
+
+async function main() {
+  let raw = '';
+  process.stdin.setEncoding('utf8');
+  for await (const chunk of process.stdin) raw += chunk;
+  const request = JSON.parse(raw);
+  if (request?.schemaVersion !== 'helix.bridge-plugin-request/1') throw new Error('unsupported Bridge plugin request');
+  const source = resolve(request.source.source);
+  const outputDir = resolve(request.outputDir);
+  mkdirSync(outputDir, { recursive: true });
+  const assessment = assess(source);
+  const selected = assessment.selected;
+  const output = join(outputDir, `${selected.id}.glb`);
+  let conversion = await convert(source, selected, output, false);
+  stampBridgeProvenance(output, source, selected);
+  let qa = auditVehicleGlb(output, { sourceRoot: selected.root, hasAudio: selected.hasAudio });
+  if (qa.findings.some((row) => row.code === 'frame.forward-semantics' && row.status === 'error') && selected.glbs.length === 0) {
+    conversion = await convert(source, selected, output, true);
+    stampBridgeProvenance(output, source, selected);
+    qa = auditVehicleGlb(output, { sourceRoot: selected.root, hasAudio: selected.hasAudio });
+  }
+  const report = {
+    schemaVersion: 'helix.beamng-vehicle-import/1',
+    selected: selected.id,
+    assessment: assessment.candidates.map((row) => ({ id: row.id, eligible: row.blockers.length === 0,
+      score: row.score, blockers: row.blockers, jbeam: row.jbeams.length, geometry: row.daes.length + row.glbs.length,
+      materials: row.materials.length, audio: row.audio.length,
+      audioReferences: row.audioReferences, cabinSignals: row.cabin, authoredSteering: row.authoredSteering,
+      authoredTyres: row.authoredTyres, tyreDependency: dependencyReceipt(row.tyreDependency), wheelSignals: row.wheels })),
+    conversion,
+    qa,
+  };
+  writeFileSync(join(outputDir, 'beamng-import-report.json'), `${JSON.stringify(report, null, 2)}\n`);
+  if (!qa.eligible) {
+    throw new Error(`converted vehicle failed acceptance:\n${qa.findings.filter((row) => row.status === 'error').map((row) => `- ${row.code}: ${JSON.stringify(row.measured)} (${row.requirement})`).join('\n')}`);
+  }
+  process.stdout.write(JSON.stringify({ artifacts: [{ kind: 'format.glb', path: basename(output), metadata: report }] }));
+}
+
+main().catch((error) => { process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`); process.exitCode = 1; });