@helix3/helix-cli 0.1.18-helix3.359 → 0.1.18-helix3.361

package/README.md

@@ -46,6 +46,7 @@ The token is stored in `~/.helix/credentials.json` (mode `600`). It's sent as
 | `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 vehicle preview <dir-or-package.json> [--glb <model.glb>] [--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`. Exit `0` pass, `1` fail, `2` could not measure. See [docs/vehicle-preview.md](docs/vehicle-preview.md). |
 | `helix vehicle publish <dir> [--dry-run] [--item <id> --package-version <v> --reason <text>] [--json]` | One command from a vehicle package directory to a sealed, pinned, read-back-verified vehicle item: validate → upload each local WAV and write its verified public URL → mint → seal + pin the `vehicle` Package → read back. Resumable (ledger in `<dir>/.helix-publish`). See [Vehicle publish](#vehicle-publish). |
 | `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> [--grant] [--json]` / `helix vehicle addon publish <dir> [--no-grant] [--dry-run]` | Add-on fit gate (contract, `helixMeshFrame` anchoring, host hubs, hide targets + grants, the backend's `validate-fit` dry run) and the end-to-end add-on publish (grant → upload → seal + pin the `addon` Package → read back). |

package/dist/index.js

@@ -617,6 +617,53 @@ vehicleCommand
     if (!result.ok)
         process.exitCode = 1;
 });
+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. '
+    + 'Nothing is uploaded or recorded. Exit 0 = every blocking check passed, 1 = a check failed, 2 = could not measure')
+    .argument('<dir-or-package.json>', 'a directory holding vehicle-package.json + model.glb (the layout `vehicle publish` reads), or the package JSON itself')
+    .option('--glb <model.glb>', 'the model (default: model.glb, or the one .glb, beside the package)')
+    .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')
+    .option('--occupants', 'also seat an avatar in every seat and judge the cabin (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')
+    .option('--web-url <url>', 'website base URL (default: the site that serves --api-url)')
+    .option('--json', 'print the machine-readable summary (also written to <out>/preview.json)')
+    .action(async (target, opts) => {
+    try {
+        const { PreviewInputError, renderPreviewText, runVehiclePreview } = await Promise.resolve().then(() => __importStar(require('./vehicle/preview')));
+        const creds = (0, config_1.loadCredentials)();
+        const apiBase = opts.apiUrl ?? creds?.apiUrl ?? config_1.DEFAULT_API_URL;
+        const webBase = opts.webUrl ?? process.env.HELIX_WEB_URL ?? (0, config_1.webUrlForApi)(apiBase) ?? config_1.DEFAULT_WEB_URL;
+        let summary;
+        try {
+            summary = await runVehiclePreview({
+                target, glb: opts.glb, out: opts.out, proxyItem: opts.proxyItem, occupants: opts.occupants, apiBase, webBase,
+                token: creds?.token ?? null, storageState: opts.storageState ?? process.env.HELIX_VQA_STORAGE_STATE, chrome: opts.chrome, quiet: opts.json,
+            });
+        }
+        catch (error) {
+            if (error instanceof PreviewInputError) {
+                process.stderr.write(`✖ ${error.message}\n`);
+                process.exitCode = 2;
+                return;
+            }
+            throw error;
+        }
+        if (opts.json)
+            console.log(JSON.stringify(summary, null, 2));
+        else
+            console.log(renderPreviewText(summary));
+        process.exitCode = summary.exitCode;
+    }
+    catch (error) {
+        process.stderr.write(`✖ vehicle preview could not run: ${error instanceof Error ? (error.stack ?? error.message) : String(error)}\n`);
+        process.exitCode = 2;
+    }
+});
 // ── vehicle publish / audio / add-on tooling (src/vehicle/{publish,audio,addon}.ts) ───────────────────────────────
 function vehicleContinuumDeps() {
     const creds = requireAuth();