@helix3/helix-cli 0.1.18-helix3.347 → 0.1.18-helix3.349

package/README.md

@@ -45,6 +45,7 @@ The token is stored in `~/.helix/credentials.json` (mode `600`). It's sent as
 | `helix validate [dir]` | Validate a bundle locally — the exact rules the server enforces. |
 | `helix publish [dir] [--thumbnail <file>] [--upload-source] [--source-dir <path>]` | Validate → resolve/create the world → upload files → finalize → set the cover image → print the play URL. `--upload-source` additionally sends the project's source through a separate private channel so the world can be edited on the website later — **off by default**. |
 | `helix list` | List your worlds. |
+| `helix vehicle validate <vehicle-package.json> [--glb <model.glb>] [--json]` | One-second local gate for a hand-authored Universal Vehicle, run before `item publish`. Checks the package against the engine's own validator (vendored, pinned to an engine commit), the engine publish gate, the backend pin requirements, `groundToBodyOrigin` vs `wheelRadius + staticRideHeight`, and the `componentBuild` digest; with `--glb` also resolves the four wheel nodes, checks each wheel node's origin is at its hub (`WHEEL_PIVOT_NOT_AT_HUB`), the +X-left / +Z-forward frame, the vehicle publish budgets and the articulation nodes. Exit `0` no errors, `1` errors, `2` unreadable input. See [Vehicle validate](#vehicle-validate). |
 | `helix item list-slots [--json]` | Print the Character-Creator vocabulary a wearable declares: the cosmetic slot tags, and the genders. |
 | `helix item publish <mesh.glb> --title <t> [--collectible-supply <n>] [initial distribution flags] [--dry-run\|--quote]` | Publish a Standard item by default, or one fixed-supply Collectible. The item definition is separate from acquisition routes. |
 | `helix item distribution create\|list\|update\|disable …` | Manage Marketplace/World Claim or Buy routes without republishing the item or paying another publish fee. |
@@ -545,6 +546,27 @@ How each field is resolved, and what a null means:
   and **no `vault` key** — absent, not `null`, so "not looked up" cannot be read as "not there".
 - Lookups run at most 8 in flight and are cached for the life of the process.
 
+## Vehicle validate
+
+`helix vehicle validate <vehicle-package.json> [--glb <model.glb>] [--json]` needs no login and no network.
+A vehicle that did not come through the BeamNG bridge is otherwise validated against nothing: `item publish`
+returns ok and the runtime then refuses to spawn it. `helix item publish --kind vehicle` now runs the package
+checks on `--vehicle-package` itself (publish, `--dry-run` and `--quote`) and refuses on any error.
+
+Every finding prints as `CODE  path — message` plus a `fix:` line; `--json` returns
+`{ ok, errors, warnings, issues: [{ code, level, path, message, fix }], engineCommit }`.
+
+| Layer | Codes |
+|---|---|
+| Engine validator (all its errors and warnings) | `ENGINE_VALIDATOR`, `ENGINE_VALIDATOR_CRASH` |
+| Publish gate + backend pin | `PACKAGE_NOT_OBJECT`, `PACKAGE_VERSION_UNSUPPORTED`, `SCHEMA_VERSION_MISMATCH`, `REQUIRED_FIELD_MISSING`, `REQUIRED_BLOCK_MISSING`, `MESH_CLASS_ID_MISSING`, `MESH_PARTS_MISSING`, `WHEEL_VISUALS_MISSING`, `WHEEL_VISUALS_INVALID`, `NOT_DISTRIBUTABLE`, `MESH_SOURCE_FIXTURE`, `PUBLISH_GATE` |
+| Cross-field | `GROUND_TO_BODY_ORIGIN_MISMATCH` (> 5 mm; fix the ride height, the field is locked after first publish), `COMPONENT_BUILD_DIGEST_MISMATCH` (prints the computed digest), `COMPONENT_ACTIONS_MISMATCH` (prints the compiled protocol), `COMPONENT_BUILD_INVALID`, `PANEL_SIGNAL_NO_ACTION` (warn), `SEAT_SOCKET_UNKNOWN` (warn) |
+| `--glb` | `WHEEL_NODES_MISSING`, `WHEEL_PIVOT_NOT_AT_HUB` (origin > 2 cm from the centre of its geometry — the wheel add-on anchor lands there), `WHEEL_ORIGINS_NOT_DISTINCT`, `WHEEL_FRAME_MIRRORED_X`, `WHEEL_FRAME_FRONT_NOT_PLUS_Z`, `WHEEL_NODE_EMPTY` (warn), `LENGTH_NOT_ALONG_Z` (warn), `PANEL_NODE_MISSING`, `VEHICLE_BUDGET_TRIANGLES` / `_MATERIALS` / `_TEXTURE_EDGE` / `_DRAW_CALLS` / `_FILE_SIZE` |
+
+The model frame is glTF: +X is the vehicle's left, +Y up, +Z forward, metres. Wheel nodes are found by name with
+the engine's own resolver (`wheel_lf` / `wheel_rf` / `wheel_lr` / `wheel_rr` and the usual aliases); all four must
+resolve. The engine validator is vendored by `scripts/vendor-vehicle-package-v2.mjs` (see `vendor/README.md`).
+
 ## Item publish flow
 
 `helix item publish` creates an item definition. It defaults to **Standard**: unlimited issuance,

package/dist/index.js

@@ -40,6 +40,7 @@ const normalMapGuard_1 = require("./character/normalMapGuard");
 const itemSetVersion_1 = require("./itemSetVersion");
 const moveUx_1 = require("./visualQa/moveUx");
 const restFrameGuard_1 = require("./character/restFrameGuard");
+const validate_1 = require("./vehicle/validate");
 const commander_1 = require("commander");
 const commands_1 = require("./sceneHlod/commands");
 const placementRequest_1 = require("./placementRequest");
@@ -555,6 +556,58 @@ deviceCommand
     if (reports.some((report) => !report.ok))
         process.exitCode = 1;
 });
+const vehicleCommand = program
+    .command('vehicle')
+    .description('Check a Universal Vehicle before publish');
+vehicleCommand
+    .command('validate')
+    .description('Validate a vehicle package (and optionally its GLB) against the engine contract, the backend pin rules and the publish budgets. '
+    + 'Exit 0 = no errors, 1 = errors, 2 = unreadable input')
+    .argument('<vehicle-package.json>', 'the vehicle package JSON (the file given to `item publish --vehicle-package`)')
+    .option('--glb <model.glb>', 'also check the model: wheel nodes and pivots, frame orientation, budgets, articulation nodes')
+    .option('--json', 'print the machine-readable report')
+    .action(async (packageFile, opts) => {
+    let pkg;
+    let glb;
+    try {
+        pkg = (0, validate_1.readJsonFile)((0, node_path_1.resolve)(packageFile));
+    }
+    catch (error) {
+        process.stderr.write(`✖ cannot read vehicle package ${packageFile}: ${error instanceof Error ? error.message : String(error)}\n`);
+        process.exitCode = 2;
+        return;
+    }
+    if (opts.glb !== undefined) {
+        try {
+            glb = (0, node_fs_1.readFileSync)((0, node_path_1.resolve)(opts.glb));
+        }
+        catch (error) {
+            process.stderr.write(`✖ cannot read GLB ${opts.glb}: ${error instanceof Error ? error.message : String(error)}\n`);
+            process.exitCode = 2;
+            return;
+        }
+    }
+    let result;
+    try {
+        result = await (0, validate_1.validateVehicle)(pkg, glb);
+    }
+    catch (error) {
+        process.stderr.write(`✖ cannot validate ${opts.glb ?? packageFile}: ${error instanceof Error ? error.message : String(error)}\n`);
+        process.exitCode = 2;
+        return;
+    }
+    if (opts.json) {
+        console.log(JSON.stringify({ file: (0, node_path_1.resolve)(packageFile), glb: opts.glb ? (0, node_path_1.resolve)(opts.glb) : null, ...result }, null, 2));
+    }
+    else {
+        if (result.issues.length > 0)
+            console.log((0, validate_1.formatVehicleIssues)(result.issues));
+        console.log(`${result.ok ? '✔' : '✖'} ${result.ok ? 'Valid' : 'Invalid'} vehicle package: ${result.errors} error${result.errors === 1 ? '' : 's'}, ${result.warnings} warning${result.warnings === 1 ? '' : 's'}`
+            + `${glb ? ' (package + GLB)' : ' (package only — add --glb <model.glb> to check wheels, pivots and budgets)'}  [engine ${result.engineCommit.slice(0, 8)}]`);
+    }
+    if (!result.ok)
+        process.exitCode = 1;
+});
 // Validate a token against the API, then persist it. Shared by the browser
 // flow and the --token (CI/headless) path.
 async function finishLogin(apiUrl, token) {
@@ -1638,6 +1691,7 @@ item
     if (opts.dryRun) {
         try {
             const plan = (0, lib_1.planItemPublish)(publishOptions);
+            const vehicleWarnings = await (0, validate_1.assertPublishVehiclePackage)(publishOptions);
             await (0, baseColorGuard_1.assertPublishBaseColor)(publishOptions, plan.meshBytes);
             await (0, normalMapGuard_1.assertPublishNormalMaps)(publishOptions, plan.meshBytes);
             await (0, restFrameGuard_1.assertPublishRestFrames)(publishOptions, plan.meshBytes);
@@ -1649,6 +1703,7 @@ item
                     mesh: plan.mesh,
                     thumbnail: plan.thumbnail,
                     warnings: plan.warnings,
+                    ...(vehicleWarnings.length > 0 ? { vehicleWarnings } : {}),
                 }, null, 2));
                 return;
             }
@@ -1659,6 +1714,8 @@ item
             console.log(`  payload:   ${JSON.stringify(plan.payload, null, 2).replace(/\n/g, '\n             ')}`);
             for (const warning of plan.warnings)
                 console.log(`  • ${warning}`);
+            if (vehicleWarnings.length > 0)
+                console.log((0, validate_1.formatVehicleIssues)(vehicleWarnings));
             const status = (0, lib_1.authStatus)();
             if (!status.loggedIn)
                 console.log('  • not logged in — run `helix login` before the real publish');