@helix3/helix-cli 0.1.19-helix3.377 → 0.1.20-helix3.379

package/README.md

@@ -45,10 +45,12 @@ 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. |
+| `helix continuum publish-owned-item <item-id> --package-id <id> --package-version <v> --manifest-cid <cid> --content-rating <rating> --accept-rating-attestation` | Publish an existing personal Item from its unchanged public sealed Package pin. Offers are separate. |
 | `helix vehicle audio-check <dir\|package.json\|item-id> [--json]` | Proves every sound the runtime will select resolves, is PCM WAV and is audible (pre-publish on local files, or read-back on a published item). |
 | `helix vehicle addon check <dir> [--json]` | Add-on fit gate for local source and host compatibility. |
 | `helix item list-slots [--json]` | Print the Character-Creator vocabulary a wearable declares: the cosmetic slot tags, and the genders. |
@@ -84,7 +86,7 @@ The token is stored in `~/.helix/credentials.json` (mode `600`). It's sent as
 | `helix world performance-report [bundle] [--scene <scene-v2.json>] [--package <package-version.json>] [--snapshot <inspect.json>] [--perf <receipt.json>]` | Analyze exact declared scene resources and existing reference-profile budgets, while keeping authored geometry/material/delivery estimates separate from supplied runtime claims. Prints actionable instancing, Palette, lighting, transfer, and visual-QA guidance; it never predicts FPS from static counts. |
 | `helix world scene-source inventory\|compile <helsinki\|bistro> <archive>` | Verify and safely inventory a known CC BY source archive, then compile deterministic local proxy/detail GLBs and an existing-schema Scene v2 package. |
 | `helix world scene-source publish <world-id> <package-dir> [--publish]` | Validate the Scene v2 package and print its multipart build receipt. Execution remains dry-run-only until backend private-pin entitlement lands; `--publish` currently fails closed, and access control never changes CC BY rights. |
-| `helix continuum publish-source-map\|publish-scratch\|publish-package\|publish-glb\|make-item` | Resume exact-CID object adoption/ingestion, Package lease/seal, optional explicitly authorized Listing, and WorldRelease publication through one creator-owned pipeline. |
+| `helix continuum publish-source-map\|publish-scratch\|publish-package\|publish-glb\|make-item\|publish-owned-item` | Resume exact-CID object adoption/ingestion, Package lease/seal, optional explicitly authorized Listing, and WorldRelease publication through one creator-owned pipeline. |
 | `helix continuum receipt <job-id>` | Read the sanitized durable receipt for a completed Continuum publication. |
 | `helix unreal init\|validate\|doctor\|package [project]` | Create and gate a shared-runtime or native-game publish manifest, check optional editor MCP, and assemble a local upload-shaped package. |
 | `helix unreal publish <candidate> --world <slug>` | Upload a **cooked** Unreal world to HELIX: verify the candidate, presign, upload every artifact, finalize, and promote it as the world's active build. |
@@ -569,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 }`.
@@ -580,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
@@ -632,6 +639,21 @@ Creating an Item without an active offer grants no creator copy. The same intent
 interrupted call. The backend derives specialized Item metadata from the sealed Package root;
 client supplied host, fit, operation and rider metadata is never trusted.
 
+An Item created with `make-item --personal` keeps its identity when published later. First make
+its Package public and confirm the current sealed pin, then attest its rating and publish that
+existing Item. Publishing opens no acquisition route or creator copy; create a Marketplace or
+World Distribution afterward when it should become available:
+
+```bash
+helix continuum publish-owned-item <item-uuid> --package-id <uuid> \
+  --package-version 1.0.0 --manifest-cid cid:sha256:<64-hex> \
+  --content-rating everyone --accept-rating-attestation --json
+```
+
+Use `--intent-id <uuidv4>` to retry an interrupted promotion safely. The server requires the
+Package to be public, sealed, current, owned by the creator, and pinned to that Item. A private
+Package cannot be promoted through this Item command.
+
 Existing Item reads, distributions, visual QA and Package Version moves remain available. The
 former Item-first authoring commands are retired from CLI discovery.
 Vehicle, add-on, locomotion and interactive definition authors must seal the appropriate Package

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;
@@ -707,6 +715,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 '
@@ -4660,6 +4739,47 @@ continuum
         fail(error instanceof lib_1.ApiError ? error.render() : `✖ ${error instanceof Error ? error.message : String(error)}`);
     }
 });
+continuum
+    .command('publish-owned-item')
+    .description('Publish an existing personal Item from its exact sealed public Package pin; open offers separately')
+    .argument('<item-id>', 'existing Item UUID; identity is preserved')
+    .requiredOption('--package-id <uuid>', 'owned sealed Package UUID')
+    .requiredOption('--package-version <semver>', 'exact current sealed Package Version')
+    .requiredOption('--manifest-cid <cid>', 'exact immutable manifest CID')
+    .requiredOption('--content-rating <rating>', 'creator-attested rating: everyone, teen, mature or adult')
+    .option('--accept-rating-attestation', 'attest that the stated content rating is accurate')
+    .option('--intent-id <uuidv4>', 'stable UUIDv4 for safe retry after an interrupted request')
+    .option('--json', 'emit the unchanged Item and publication receipt')
+    .action(async (itemId, opts) => {
+    try {
+        if (opts.acceptRatingAttestation !== true)
+            throw new Error('--accept-rating-attestation is required to publish an Item');
+        if (!['everyone', 'teen', 'mature', 'adult'].includes(opts.contentRating))
+            throw new Error('--content-rating must be everyone, teen, mature or adult');
+        const creds = requireAuth();
+        const mismatch = (0, config_1.credsEnvMismatchWarning)(creds.apiUrl);
+        if (mismatch)
+            throw new Error(`Refusing to publish an Item:\n${mismatch}`);
+        const { publishOwnedItemFromPackage } = await Promise.resolve().then(() => __importStar(require('./publications')));
+        const receipt = await publishOwnedItemFromPackage({
+            itemId,
+            intentId: opts.intentId,
+            packagePin: { packageId: opts.packageId, version: opts.packageVersion, manifestCid: opts.manifestCid },
+            contentRating: opts.contentRating,
+            acceptRatingAttestation: true,
+        }, creds);
+        if (opts.json)
+            console.log(JSON.stringify(receipt, null, 2));
+        else {
+            console.log(`✔ Published existing Package-backed Item ${receipt.item.id}`);
+            console.log(`  package: ${receipt.item.packagePin.packageId}@${receipt.item.packagePin.version}`);
+            console.log('  offers: none opened; use helix item distribution create when ready');
+        }
+    }
+    catch (error) {
+        fail(error instanceof lib_1.ApiError ? error.render() : `✖ ${error instanceof Error ? error.message : String(error)}`);
+    }
+});
 continuum
     .command('publish-glb')
     .description('Seal a GLB as a Continuum Prop or Character Package; optionally open a Marketplace or World offer')
@@ -4745,6 +4865,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 } : {}),