@helix3/helix-cli 0.1.20-helix3.378 → 0.1.20-helix3.380

package/README.md

@@ -45,7 +45,8 @@ 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 Package publication. 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 vehicle simulate <dir\|vehicle-package.json> [--item <id>] [--spec <file>] [--offline] [--json]` | Drive the package offline with the platform's **own** engine instrument (the runtime `^0.3` serves today, cached by sha; offline = last cached, labelled) and judge 0-100 km/h, 0-60 mph, quarter mile, top speed, 100-0 km/h / 60-0 mph braking, skidpad g, turbo lag and the rest pose against the package `targets` and `--spec`. Exit `0` pass, `1` a figure out of tolerance, `2` could not simulate. See [docs/vehicle-simulate.md](docs/vehicle-simulate.md). |
+| `helix vehicle validate <vehicle-package.json> [--glb <model.glb>] [--no-simulate] [--json]` | One-second local gate for a hand-authored Universal Vehicle, run before Package publication. 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 the articulation nodes and the add-on host manifest (`asset.extras.HELIX_vehicle`); drives packages that declare `targets` (`helix vehicle simulate`). Exit `0` no errors, `1` errors, `2` unreadable input. See [Vehicle validate](#vehicle-validate). |
 | `helix vehicle preview [<dir-or-package.json>] [--glb <model.glb>] [--addon <dir>]… [--item <id>] [--tolerance-cm <cm>] [--out <dir>] [--proxy-item <id>] [--json]` | Render a vehicle that is **not published yet** headless in the real runtime (hosted test grounds, Try Now through a published proxy vehicle whose car is swapped for your package + GLB, served from disk; nothing uploaded or recorded) and measure it: body-origin height against the declared `groundToBodyOrigin` (the number that locks at first mint), wheels on their hubs, arch clearance, rolling radius vs `wheelRadius`, steering, doors, seats. Prints a numeric summary with PASS/FAIL per check and writes frames, a contact sheet, `bundle.json` and `preview.json`. Boards with the candidate's own seat ids. With `--addon <dir>` (repeatable) it previews unpublished vehicle **add-ons** instead: fits each to the candidate car or a published car and measures the drawn geometry in world space against its anchor (wheels within 1 cm of each hub, socket/host-framed parts at their mount, not at the car's origin; tune-only ops read back from the live tuning). Exit `0` pass, `1` fail, `2` could not measure. See [docs/vehicle-preview.md](docs/vehicle-preview.md). |
 | `helix continuum publish-glb <mesh.glb> --title <t> [--package-type asset\|character] [--offer marketplace\|world --price-lix <n> --content-rating <rating>]` | Seal a Package first; optional offer makes it ownable. See [Package-first GLB publication](#package-first-glb-publication). |
 | `helix continuum make-item --package-id <id> --package-version <v> --manifest-cid <cid> --content-rating <rating> [--offer marketplace\|world --price-lix <n>]` | Project one exact sealed Package Version into an Item, with an optional first offer. |
@@ -570,8 +571,11 @@ How each field is resolved, and what a null means:
 
 ## Vehicle validate
 
-`helix vehicle validate <vehicle-package.json> [--glb <model.glb>] [--json]` needs no login and no network.
-This local gate checks the vehicle Package and optional GLB before any publication.
+`helix vehicle validate <vehicle-package.json> [--glb <model.glb>] [--no-simulate] [--offline] [--json]` needs no login.
+This local gate checks the vehicle Package and optional GLB before any publication. When the package declares
+`targets` it also drives the car with the platform's engine instrument (`helix vehicle simulate`; the runtime is
+fetched once and cached, `--offline` uses the cache, `--no-simulate` skips the drive) and reports every figure
+outside its tolerance as `SIMULATED_PERFORMANCE_OUT_OF_TOLERANCE`.
 
 Every finding prints as `CODE  path — message` plus a `fix:` line; `--json` returns
 `{ ok, errors, warnings, issues: [{ code, level, path, message, fix }], engineCommit }`.
@@ -581,6 +585,8 @@ Every finding prints as `CODE  path — message` plus a `fix:` line; `--json` re
 | 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) |
+| Drive (package `targets`) | `SIMULATED_PERFORMANCE_OUT_OF_TOLERANCE` (figure, simulated, target, error, tolerance, engine version), `SIMULATED_REST_POSE_INVALID`, `SIMULATION_UNAVAILABLE` (warn: no runtime reachable or cached) |
+| `--glb` host manifest | `HOST_MANIFEST_MISSING`, `HOST_MANIFEST_MISPLACED` (found in scene/document/node extras; the backend reads only `asset.extras.HELIX_vehicle`), `HOST_MANIFEST_EMPTY`, `HOST_MANIFEST_DIVERGENT`, `HOST_MANIFEST_SOCKET_INVALID`, `HOST_MANIFEST_SOCKET_NAME_INVALID`, `HOST_MANIFEST_SOCKET_NODE_MISSING`. `helix continuum publish-package` refuses a `vehicle` Package descriptor whose model GLB has any of these errors before sealing. See [docs/vehicle-simulate.md](docs/vehicle-simulate.md#host-manifest) |
 | `--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

package/dist/index.js

@@ -574,7 +574,10 @@ vehicleCommand
     .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 that will be sealed in the Vehicle Package')
-    .option('--glb <model.glb>', 'also check the model: wheel nodes and pivots, frame orientation, budgets, articulation nodes')
+    .option('--glb <model.glb>', 'also check the model: wheel nodes and pivots, frame orientation, budgets, articulation nodes, and the add-on host manifest (asset.extras.HELIX_vehicle)')
+    .option('--no-simulate', 'skip the offline drive (by default a package with `targets` is driven by the platform\'s own engine instrument and every figure outside its tolerance is an ERROR)')
+    .option('--offline', 'drive with the last cached engine runtime; never fetch')
+    .option('--api-url <url>', 'API whose engine runtime drives the car (default: this CLI\'s environment)')
     .option('--json', 'print the machine-readable report')
     .action(async (packageFile, opts) => {
     let pkg;
@@ -605,7 +608,7 @@ vehicleCommand
         const { provisionalAudio } = await Promise.resolve().then(() => __importStar(require('./vehicle/audio')));
         const prepared = provisionalAudio(pkg, (0, node_path_1.resolve)(packageFile, '..'));
         provisional = prepared.filled;
-        result = await (0, validate_1.validateVehicle)(prepared.pkg, glb);
+        result = await (0, validate_1.validateVehicle)(prepared.pkg, glb, opts.simulate === false ? {} : { simulate: { apiUrl: opts.apiUrl ?? config_1.DEFAULT_API_URL, offline: opts.offline } });
     }
     catch (error) {
         process.stderr.write(`✖ cannot validate ${opts.glb ?? packageFile}: ${error instanceof Error ? error.message : String(error)}\n`);
@@ -618,10 +621,15 @@ vehicleCommand
     else {
         if (result.issues.length > 0)
             console.log((0, validate_1.formatVehicleIssues)(result.issues));
+        if (result.simulation) {
+            const { formatSimulationReport } = await Promise.resolve().then(() => __importStar(require('./vehicle/simulate')));
+            console.log(formatSimulationReport(result.simulation).split('\n').map((line) => `  ${line}`).join('\n'));
+        }
         if (provisional > 0)
             console.log(`  ${provisional} audio row${provisional === 1 ? '' : 's'} backed by a local WAV: seal the WAV in the Vehicle Package before making its Item; \`helix vehicle audio-check\` proves ${provisional === 1 ? 'it plays' : 'they play'}`);
         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)}]`);
+            + `${glb ? ' (package + GLB)' : ' (package only — add --glb <model.glb> to check wheels, pivots, budgets and the host manifest)'}`
+            + `${result.simulation ? ` + drive (engine runtime ${result.simulation.runtime.version})` : opts.simulate === false ? ' (drive skipped: --no-simulate)' : ''}  [validator ${result.engineCommit.slice(0, 8)}]`);
     }
     if (!result.ok)
         process.exitCode = 1;
@@ -630,6 +638,7 @@ vehicleCommand
     .command('preview')
     .description('Render a vehicle that is not published yet in the real HELIX runtime (headless) and measure it: ride height against groundToBodyOrigin, '
     + 'wheels on their hubs, arch clearance, rolling radius, steering, doors, seats. Run it BEFORE the first mint, which locks groundToBodyOrigin. '
+    + 'Every car preview also writes the fixed appearance poses (poses/pose.front|side|rear|top|front34|rear34|cockpit.jpg and poses.jpg) to compare with reference photos. '
     + 'With --addon <dir> it previews unpublished vehicle ADD-ONS instead: each add-on directory (the layout `vehicle addon check|publish` reads) is fitted '
     + 'to the candidate car, or to a published car (--item <id>, no car directory) by the engine\'s own fold, and the DRAWN geometry is measured in world space '
     + 'against its anchor (wheels within 1 cm of each hub, socket-framed parts on their socket, host-framed parts at their authored position, inside the car, '
@@ -642,7 +651,7 @@ vehicleCommand
     .option('--tolerance-cm <cm>', 'with --addon: how far a drawn part may sit from its anchor (default: wheels 1 cm, socket-framed and host-framed parts 3 cm)', (v) => Number(v))
     .option('--out <dir>', 'frames, contact-sheet.jpg, bundle.json and preview.json go here (default: <dir>/.helix-preview)')
     .option('--proxy-item <id>', 'a published vehicle the QA account can Try Now; the runtime loads it and the candidate replaces its car (and its slot board is what --addon fits to)')
-    .option('--occupants', 'also seat an avatar in every seat and judge the cabin (slow)')
+    .option('--occupants', 'also seat an avatar in every seat, judge the cabin, and report where the runtime\'s cabin fit put each seat vs where it was authored (slow)')
     .option('--storage-state <file>', 'Playwright storageState of a signed-in QA account (default: sign in with `helix login`, or $HELIX_VQA_STORAGE_STATE)')
     .option('--chrome <path>', 'Chromium executable (default: Playwright Chromium / Chrome for Testing, headless; the macOS system Chrome is refused)')
     .option('--api-url <url>', 'platform API base URL')
@@ -707,6 +716,77 @@ function printVehicleJsonOr(json, value, human) {
     else
         human();
 }
+vehicleCommand
+    .command('simulate')
+    .description('Drive a vehicle package offline with the platform\'s OWN engine instrument (the runtime `^0.3` serves today: Rapier, land solver v2, the code players run) '
+    + 'and judge it: 0-100 km/h, 0-60 mph, quarter mile, top speed (converged or not), 100-0 km/h and 60-0 mph braking, skidpad lateral g, turbo lag, '
+    + 'gears used and the rest pose. Every figure is compared with the package\'s own `targets` (and --spec): error = (simulated - target) / target, '
+    + 'PASS iff |error| <= tolerance. The runtime is fetched once per version and cached by sha under ~/.helix/cache/engine-runtime; offline, the last '
+    + 'cached runtime is used and labelled. TURBO LAG: with boostTorqueCoef 0 the solver adds no boost torque, so a turbo car whose curve is the full-boost '
+    + 'dyno curve pulls with no lag; author lag by derating the torque curve below spool, then check `turbo lag` here (docs/vehicle-simulate.md). '
+    + 'Exit 0 = every compared figure passes, 1 = a figure is out of tolerance or the rest pose is wrong, 2 = could not simulate')
+    .argument('[dir-or-package.json]', 'a vehicle package directory (vehicle-package.json), the package JSON, or a saved item read')
+    .option('--item <id>', 'simulate a PUBLISHED vehicle item\'s stored package (public read) instead of a local file')
+    .option('--spec <file>', 'extra targets: a package / {targets}, or a reference spec (perf.0_100_kmh_s, perf.braking_100_0_m, perf.braking_70mph_0_m, perf.skidpad_g, perf.turbo_lag_s … as {value, tol_pct})')
+    .option('--offline', 'use the last cached engine runtime; never fetch')
+    .option('--runtime <file-or-url>', 'drive with this runtime bundle instead of the served one (a candidate engine build)')
+    .option('--range <range>', 'engine range to resolve (default ^0.3)')
+    .option('--api-url <url>', 'API to resolve the runtime (and --item) from (default: this CLI\'s environment)')
+    .option('--json', 'print the machine-readable report')
+    .action(async (input, opts) => {
+    const { readVehiclePackageArg, simulateVehicle, targetsFromSpec, formatSimulationReport } = await Promise.resolve().then(() => __importStar(require('./vehicle/simulate')));
+    const { loadEngineRuntime } = await Promise.resolve().then(() => __importStar(require('./vehicle/simulateRuntime')));
+    const { provisionalAudio } = await Promise.resolve().then(() => __importStar(require('./vehicle/audio')));
+    const apiUrl = (opts.apiUrl ?? config_1.DEFAULT_API_URL).replace(/\/$/, '');
+    let pkg;
+    let source;
+    let specTargets;
+    try {
+        if (opts.item) {
+            // A public read; retried on a 5xx so one flaky gateway answer does not read as "no such car".
+            let res = await fetch(`${apiUrl}/api/v1/universal-items/${encodeURIComponent(opts.item)}`, { headers: { accept: 'application/json' } });
+            for (let attempt = 1; res.status >= 500 && attempt < 4; attempt += 1) {
+                await new Promise((done) => setTimeout(done, 1000 * attempt));
+                res = await fetch(`${apiUrl}/api/v1/universal-items/${encodeURIComponent(opts.item)}`, { headers: { accept: 'application/json' } });
+            }
+            if (!res.ok)
+                throw new Error(`GET /api/v1/universal-items/${opts.item} answered HTTP ${res.status}`);
+            const body = await res.json();
+            pkg = (body.item ?? body).properties?.vehiclePackage;
+            if (!pkg)
+                throw new Error(`item ${opts.item} carries no properties.vehiclePackage`);
+            source = `item ${opts.item}`;
+        }
+        else {
+            if (!input)
+                throw new Error('pass a vehicle package directory or JSON file, or --item <id>');
+            const read = readVehiclePackageArg(input);
+            pkg = provisionalAudio(read.pkg, read.dir).pkg;
+            source = read.file;
+        }
+        if (opts.spec)
+            specTargets = targetsFromSpec(JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.resolve)(opts.spec), 'utf8')), opts.spec);
+    }
+    catch (error) {
+        process.stderr.write(`✖ ${error instanceof Error ? error.message : String(error)}\n`);
+        process.exitCode = 2;
+        return;
+    }
+    try {
+        const runtime = await loadEngineRuntime({ apiUrl, offline: opts.offline, runtime: opts.runtime, range: opts.range });
+        const report = await simulateVehicle(pkg, runtime, { specTargets });
+        if (opts.json)
+            console.log(JSON.stringify({ source, spec: opts.spec ? (0, node_path_1.resolve)(opts.spec) : null, ...report }, null, 2));
+        else
+            console.log(formatSimulationReport(report));
+        if (!report.ok)
+            process.exitCode = 1;
+    }
+    catch (error) {
+        process.stderr.write(`✖ cannot simulate ${source}: ${error instanceof Error ? error.message : String(error)}\n`);
+        process.exitCode = 2;
+    }
+});
 vehicleCommand
     .command('audio-check')
     .description('Prove every sound a vehicle declares will actually play: each engine-ladder rung and slot sample the runtime selects must resolve (a local WAV '
@@ -4786,6 +4866,9 @@ continuum
         const { readContinuumPublicationFile } = await Promise.resolve().then(() => __importStar(require('./continuum/cli')));
         const loaded = await readContinuumPublicationFile(path);
         const descriptor = loaded.input;
+        // A vehicle model the backend cannot read as an add-on host would seal a silent non-host (docs/vehicle-simulate.md).
+        const { assertVehiclePackageDescriptorHost } = await Promise.resolve().then(() => __importStar(require('./vehicle/validate')));
+        assertVehiclePackageDescriptorHost(descriptor, loaded.objectPublications);
         const publication = explicitPublicListings({
             ...descriptor, sourceDigest: loaded.sourceDigest, objects: loaded.objectPublications,
             ...(opts.stage === true ? { stage: true } : {}),