@helix3/helix-cli 0.1.18-helix3.339 → 0.1.18-helix3.340

package/README.md

@@ -49,7 +49,8 @@ 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 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). With `--submit`, a PASS prints the next command (`helix item set-version …`); a 403 for a non-creator says so on the first line; `--status` also lists the item's pending (sealed, not current) versions. |
+| `helix item set-version <item-id> --package-version <v> --reason <text> [--vehicle-package <file>] [--expected-current-version-id <uuid>] [--json]` | Move an item to a sealed Package Version of its own package (pin resolved from the public Package API; `POST /api/v1/universal-items/<id>/versions`). The flow for a **listed** item: `item publish-version` seals vN and the move is refused → `item visual-qa <id> --package-version vN --submit` → `item set-version`. A refusal prints the server's message first (it names the next command), then the remedy and any hosted render it queued. An unknown version lists the sealed ones. |
 | `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

@@ -36,6 +36,8 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 const baseColorGuard_1 = require("./character/baseColorGuard");
 const normalMapGuard_1 = require("./character/normalMapGuard");
+const itemSetVersion_1 = require("./itemSetVersion");
+const moveUx_1 = require("./visualQa/moveUx");
 const commander_1 = require("commander");
 const commands_1 = require("./sceneHlod/commands");
 const placementRequest_1 = require("./placementRequest");
@@ -1266,6 +1268,7 @@ item
     .option('--ear-clearance', "with --fit-body: also clear the base body's ears (automatic for headwear/mask/hair/eyewear slot types)")
     .option('--no-ear-clearance', 'with --fit-body: skip the ear-clearance stage')
     .option('--json', 'machine-readable output')
+    .addHelpText('after', moveUx_1.VERSION_MOVE_FLOW_HELP)
     .action(async (itemId, file, opts) => {
     const creds = requireAuth();
     let meshPath = (0, node_path_1.resolve)(file);
@@ -1325,6 +1328,34 @@ item
         fail(error instanceof lib_1.ApiError ? error.render() : `✖ ${error instanceof Error ? error.message : String(error)}`);
     }
 });
+// Move a (listed) item to an already-sealed Package Version of its own package. The visual-QA gate refuses the move
+// until that version has a passing run; a refusal prints the server's message first because it names the next command.
+item
+    .command('set-version')
+    .description('Move an item to a sealed Package Version of its own package (the version-move step after `item visual-qa --package-version <v> --submit` passed)')
+    .argument('<item-id>', 'universal item UUID')
+    .requiredOption('--package-version <version>', 'the sealed version to move to, e.g. 1.0.12')
+    .requiredOption('--reason <text>', 'required, lands in the audit ledger')
+    .option('--vehicle-package <file>', 'vehicles: the version move\'s vehicle package JSON (the same file given to `item visual-qa`)')
+    .option('--expected-current-version-id <uuid>', 'refuse if the item has moved off this Package Version since you last read it')
+    .option('--json', 'machine-readable output')
+    .addHelpText('after', moveUx_1.VERSION_MOVE_FLOW_HELP)
+    .action(async (itemId, opts) => {
+    const creds = requireAuth();
+    try {
+        const { parseVehiclePackage } = await Promise.resolve().then(() => __importStar(require('./visualQa/candidate')));
+        const vehiclePackage = opts.vehiclePackage ? parseVehiclePackage((0, node_fs_1.readFileSync)(opts.vehiclePackage, 'utf8'), opts.vehiclePackage) : null;
+        const result = await (0, itemSetVersion_1.setItemVersion)(itemId, { packageVersion: opts.packageVersion, reason: opts.reason, vehiclePackage, expectedCurrentVersionId: opts.expectedCurrentVersionId }, creds);
+        if (opts.json)
+            console.log(JSON.stringify(result, null, 2));
+        else
+            for (const line of (0, itemSetVersion_1.renderSetVersionSuccess)(result))
+                console.log(line);
+    }
+    catch (error) {
+        fail(error instanceof lib_1.ApiError ? (0, itemSetVersion_1.renderSetVersionError)(error) : `✖ ${error instanceof Error ? error.message : String(error)}`);
+    }
+});
 // One command prints the whole Character-Creator vocabulary a wearable must
 // declare — the 34 slot tags AND the two genders. There is no `list-genders`:
 // a dedicated command for a closed two-value list is a command to discover, to
@@ -1730,6 +1761,7 @@ item
     .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')
+    .addHelpText('after', moveUx_1.VERSION_MOVE_FLOW_HELP)
     .action(async (id, opts) => {
     try {
         const { validateCandidateFlags, parseVehiclePackage } = await Promise.resolve().then(() => __importStar(require('./visualQa/candidate')));
@@ -1787,6 +1819,8 @@ item
                     if (job?.error)
                         console.log(`  error: ${job.error}`);
                     console.log(`current version: ${st.currentVersion ? (st.currentVersion.passed ? 'PASSED' : 'no passing run') : 'not pinned to a package version'}`);
+                    for (const line of (0, moveUx_1.describePendingVersions)(id, st.pendingVersions))
+                        console.log(line);
                 }
                 process.exitCode = job && hosted.isTerminal(job.status) ? hosted.exitCodeForJob(job) : 0;
                 return;
@@ -1849,7 +1883,7 @@ item
             quiet: opts.json,
         });
         if (opts.json) {
-            console.log(JSON.stringify({ verdict: outcome.verdict, reasons: outcome.reasons, bundleDir: outcome.bundleDir, contactSheet: outcome.contactSheet, server: outcome.server, critic: outcome.critic, timings: outcome.timings }, null, 2));
+            console.log(JSON.stringify({ verdict: outcome.verdict, reasons: outcome.reasons, nextStep: (0, moveUx_1.nextStepAfterPass)({ itemId: id, packageVersion: outcome.bundle.item.packageVersion, candidate: !!outcome.candidate, submitted: !!outcome.server, verdict: outcome.verdict, vehiclePackageFile: opts.vehiclePackage })[0]?.replace(/^\s*next:\s*/, '') ?? null, bundleDir: outcome.bundleDir, contactSheet: outcome.contactSheet, server: outcome.server, critic: outcome.critic, timings: outcome.timings }, null, 2));
         }
         else {
             const mark = outcome.verdict === 'pass' ? '✔' : '✖';
@@ -1862,6 +1896,8 @@ item
                 console.log(`  recorded: ${outcome.server.contactSheetUrl}`);
             if (!opts.submit)
                 console.log('  (local run only — add --submit to record the verdict the listing gate checks)');
+            for (const line of (0, moveUx_1.nextStepAfterPass)({ itemId: id, packageVersion: outcome.bundle.item.packageVersion, candidate: !!outcome.candidate, submitted: !!outcome.server, verdict: outcome.verdict, vehiclePackageFile: opts.vehiclePackage }))
+                console.log(line);
             console.log(`  ${(outcome.timings.totalMs / 1000).toFixed(1)} s (render ${(outcome.timings.renderMs / 1000).toFixed(1)} s)`);
         }
         process.exitCode = outcome.verdict === 'pass' ? 0 : outcome.verdict === 'fail' ? 1 : 2;
@@ -1899,7 +1935,7 @@ const itemDistribution = item
     .description('Create and manage primary Claim/Buy routes for one published item definition');
 const renderDistribution = (d) => [
     `${d.id} · ${d.channel}${d.worldSlug ? `:${d.worldSlug}/${d.key}` : ''}`,
-    `${d.priceLix === 0 ? 'Claim' : `Buy ${d.priceLix} LIX`}${d.active ? '' : ' · DISABLED'}`,
+    `${(0, lib_1.isClaimRoute)(d) ? 'Claim' : `Buy ${d.priceLix} LIX`}${d.active ? '' : ' · DISABLED'}`,
     `max/player ${d.maxPerPlayer ?? 'unlimited'} · max claims ${d.maxClaims ?? 'unlimited'}`,
 ].join(' · ');
 itemDistribution
@@ -1944,7 +1980,7 @@ itemDistribution
         if (opts.json)
             console.log(JSON.stringify(created, null, 2));
         else
-            console.log(`✔ Created ${created.priceLix === 0 ? 'Claim' : 'Buy'} route.\n  ${renderDistribution(created)}`);
+            console.log(`${(0, lib_1.distributionCreatedHeadline)(created, input.priceLix)}\n  ${renderDistribution(created)}`);
     }
     catch (err) {
         fail(err instanceof lib_1.ApiError ? err.render() : `✖ ${err instanceof Error ? err.message : String(err)}`);