@helix3/helix-cli 0.1.18-helix3.336 → 0.1.18-helix3.338

package/README.md

@@ -49,6 +49,7 @@ The token is stored in `~/.helix/credentials.json` (mode `600`). It's sent as
 | `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. |
 | `helix item visual-qa <item-id> [--submit] [--local-critic] [--storage-state <file>] [--host <id…>]` | Render the item's current package version headless in the real runtime (test-grounds world for vehicles and whole avatars, the customiser for add-ons and wearables on every declared host/base, the item viewer for props), measure it, and with `--submit` record the backend's verdict (numeric asserts + vision critic) against that exact version. **Marketplace/Vault listing, distributions and version moves on a public item require a pass.** See [docs/visual-qa.md](docs/visual-qa.md). |
+| `helix item visual-qa <item-id> --package-version <v> [--vehicle-package <file>]` | Render a version the item is **not pinned to yet**, so a refused version move can pass the gate before the pointer moves. Vehicles and avatars go through Try Now (vehicles also need the move's vehicle package), add-ons and wearables through the customiser; the bundle names the candidate, and the vehicle checksum is the one the server minted for that trial. Never falls back to the current version. See [docs/visual-qa-candidate-versions.md](docs/visual-qa-candidate-versions.md). |
 | `helix device create <dir> --id <slug> --title <t> --model <mesh.glb> --template standing-desk\|clock\|television` | Scaffold a GLB-backed `helix.device/1` definition, including the interactive TV/media-player template. There is intentionally no website Device editor. |
 | `helix device validate [dir] [--json]` | Validate the definition, GLB bytes and named-node bindings, typed state/controls, capabilities, and Home+World compatibility, including [declarative character hand reach](docs/device-hand-reach.md). |
 | `helix device test [dir] [--mode single\|multiplayer\|both] [--json]` | Exercise every interaction, persistence remount, and deterministic one-/two-client authority convergence. |

package/dist/index.js

@@ -1706,7 +1706,7 @@ item
 item
     .command('visual-qa')
     .description('Render an item headless in the real HELIX runtime, measure it, and (with --submit) record the visual-QA verdict that Marketplace/Vault listing requires. --hosted asks the platform to render it on a GPU runner instead')
-    .argument('[item-id]', 'universal item UUID (its CURRENT package version is rendered); omit with --hosted-worker')
+    .argument('[item-id]', 'universal item UUID (its CURRENT package version is rendered, or --package-version); omit with --hosted-worker')
     .option('--submit', 'submit frames + measurements to the backend, which judges and records the verdict (needs `helix login`)')
     .option('--hosted', 'queue a hosted render on the platform GPU runner and wait for the verdict (needs `helix login`; exit 0 pass, 1 fail, 2 error)')
     .option('--retry', 'with --hosted: re-queue after a failed/errored hosted run of this version')
@@ -1724,12 +1724,19 @@ item
     .option('--out <dir>', 'bundle directory (frames, bundle.json, contact-sheet.jpg)')
     .option('--storage-state <file>', 'Playwright storageState of a signed-in QA account (Try Now and the customiser need one); default $HELIX_VQA_STORAGE_STATE')
     .option('--host <id...>', 'only fit onto these host/base item ids (add-ons, wearables)')
+    .option('--package-version <version>', 'render this version of the item\'s pinned package instead of the pin: a version move judged before the pointer moves (vehicles, avatars, add-ons, wearables)')
+    .option('--vehicle-package <file>', 'with --package-version on a vehicle: the version move\'s vehicle package JSON, served by Try Now after server-side preparation')
     .option('--chrome <path>', 'Chrome/Chromium executable (default: system Chrome, headless)')
     .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 outcome as JSON')
     .action(async (id, opts) => {
     try {
+        const { validateCandidateFlags, parseVehiclePackage } = await Promise.resolve().then(() => __importStar(require('./visualQa/candidate')));
+        const flagError = validateCandidateFlags({ packageVersion: opts.packageVersion, vehiclePackageFile: opts.vehiclePackage, submitHosted: !!(opts.hosted || opts.status || opts.hostedWorker) });
+        if (flagError)
+            fail(`✖ ${flagError}`);
+        const vehiclePackage = opts.vehiclePackage ? parseVehiclePackage((0, node_fs_1.readFileSync)(opts.vehiclePackage, 'utf8'), opts.vehiclePackage) : null;
         const creds = opts.submit || opts.hosted ? requireAuth() : (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;
@@ -1833,6 +1840,8 @@ item
             out: opts.out,
             storageState: opts.storageState ?? process.env.HELIX_VQA_STORAGE_STATE,
             hostIds: opts.host,
+            packageVersion: opts.packageVersion?.trim() || null,
+            vehiclePackage,
             chrome: opts.chrome,
             submit: opts.submit,
             localCritic: opts.localCritic,