@helix3/helix-cli 0.1.18-helix3.355 → 0.1.18-helix3.357

package/README.md

@@ -56,6 +56,8 @@ The token is stored in `~/.helix/credentials.json` (mode `600`). It's sent as
 | `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). 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 item thumbnail refresh <item-id> [--force] [--dry-run] [--json]` | Re-render a published item's canonical thumbnail from its **active Package Version** with the standard server renderer (`POST /api/v1/universal-items/<id>/thumbnail/regenerate`, owner or admin). Prints the status (`generated` / `current` / `dry-run`), old -> new thumbnail URL, renderer version and the source lane + Package Version. `--dry-run` writes nothing; `--force` re-renders even when the stored thumbnail is current. Moving an item to a new Package Version now refreshes the thumbnail automatically unless you uploaded one. An older backend answers 404 and the CLI says it does not support thumbnail refresh yet. Not the world `helix thumbnail set <slug>` command. |
+| `helix item thumbnail set <item-id> <image> [--json]` | Upload your own thumbnail (png/jpg/webp, up to 10 MiB, checked locally) for a published item (`PUT /api/v1/universal-items/<id>/thumbnail`, moderated). A creator upload stays in place across version moves until you run `thumbnail refresh --force`. 403 = you are not the item's owner. |
 | `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/avatarMeshReplacement.d.ts

@@ -11,3 +11,6 @@ export interface AvatarMeshReplacementResult {
 }
 /** Replace a legacy avatar's presentation through backend authority, retaining its identity. */
 export declare function replaceAvatarMesh(itemId: string, file: string, expectedContentHash: string, credentials: CliCredentials): Promise<AvatarMeshReplacementResult>;
+export declare const PACKAGE_VERSION_HINT: string;
+/** Append the Package Version route to the server's refusal for a Package-backed avatar; other errors pass through. */
+export declare function withPackageVersionHint(rendered: string): string;

package/dist/avatarMeshReplacement.js

@@ -1,6 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.PACKAGE_VERSION_HINT = void 0;
 exports.replaceAvatarMesh = replaceAvatarMesh;
+exports.withPackageVersionHint = withPackageVersionHint;
 const promises_1 = require("node:fs/promises");
 const node_path_1 = require("node:path");
 const api_1 = require("./api");
@@ -24,4 +26,11 @@ async function replaceAvatarMesh(itemId, file, expectedContentHash, credentials)
     form.set('mesh', new Blob([new Uint8Array(bytes)], { type: 'model/gltf-binary' }), (0, node_path_1.basename)(file));
     return api_1.HelixApi.forCredentials(credentials).postMultipart(`/api/v1/universal-items/${itemId}/avatar/mesh`, form, AVATAR_REPLACEMENT_TIMEOUT_MS);
 }
+exports.PACKAGE_VERSION_HINT = 'Package-backed avatars cannot be replaced in place: seal the correction as a new Package Version ' +
+    '(`helix publish-package`), move the item onto it (`helix item set-version <item-id> --package-version <v> --reason <text>`), ' +
+    'then re-render the thumbnail with `helix item thumbnail refresh <item-id>` (or upload one with `helix item thumbnail set <item-id> <image>`).';
+/** Append the Package Version route to the server's refusal for a Package-backed avatar; other errors pass through. */
+function withPackageVersionHint(rendered) {
+    return /package-backed or adopted avatars/i.test(rendered) ? `${rendered}\n  → ${exports.PACKAGE_VERSION_HINT}` : rendered;
+}
 //# sourceMappingURL=avatarMeshReplacement.js.map

package/dist/avatarMeshReplacement.js.map

@@ -1 +1 @@
-{"version":3,"file":"avatarMeshReplacement.js","sourceRoot":"","sources":["../src/avatarMeshReplacement.ts"],"names":[],"mappings":";;AAcA,8CAuBC;AArCD,+CAA4C;AAC5C,yCAAqC;AACrC,+BAAiC;AAEjC,iCAA4C;AAE5C,MAAM,6BAA6B,GAAG,OAAO,CAAC;AAO9C,gGAAgG;AACzF,KAAK,UAAU,iBAAiB,CACrC,MAAc,EACd,IAAY,EACZ,mBAA2B,EAC3B,WAA2B;IAE3B,IAAI,CAAC,iEAAiE,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;QACpF,MAAM,IAAI,KAAK,CAAC,gCAAgC,CAAC,CAAC;IACpD,CAAC;IACD,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAAC,mBAAmB,CAAC,EAAE,CAAC;QACjD,MAAM,IAAI,KAAK,CAAC,uFAAuF,CAAC,CAAC;IAC3G,CAAC;IACD,MAAM,KAAK,GAAG,MAAM,IAAA,mBAAQ,EAAC,IAAI,CAAC,CAAC;IACnC,IAAA,yBAAkB,EAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IAChC,IAAI,KAAK,CAAC,YAAY,CAAC,CAAC,CAAC,KAAK,KAAK,CAAC,MAAM,EAAE,CAAC;QAC3C,MAAM,IAAI,KAAK,CAAC,yCAAyC,CAAC,CAAC;IAC7D,CAAC;IACD,MAAM,IAAI,GAAG,IAAI,QAAQ,EAAE,CAAC;IAC5B,IAAI,CAAC,GAAG,CAAC,qBAAqB,EAAE,mBAAmB,CAAC,WAAW,EAAE,CAAC,CAAC;IACnE,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,IAAI,IAAI,CAAC,CAAC,IAAI,UAAU,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,IAAI,EAAE,mBAAmB,EAAE,CAAC,EAAE,IAAA,oBAAQ,EAAC,IAAI,CAAC,CAAC,CAAC;IACnG,OAAO,cAAQ,CAAC,cAAc,CAAC,WAAW,CAAC,CAAC,aAAa,CACvD,2BAA2B,MAAM,cAAc,EAAE,IAAI,EAAE,6BAA6B,CACrF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"avatarMeshReplacement.js","sourceRoot":"","sources":["../src/avatarMeshReplacement.ts"],"names":[],"mappings":";;;AAcA,8CAuBC;AAQD,wDAEC;AA/CD,+CAA4C;AAC5C,yCAAqC;AACrC,+BAAiC;AAEjC,iCAA4C;AAE5C,MAAM,6BAA6B,GAAG,OAAO,CAAC;AAO9C,gGAAgG;AACzF,KAAK,UAAU,iBAAiB,CACrC,MAAc,EACd,IAAY,EACZ,mBAA2B,EAC3B,WAA2B;IAE3B,IAAI,CAAC,iEAAiE,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;QACpF,MAAM,IAAI,KAAK,CAAC,gCAAgC,CAAC,CAAC;IACpD,CAAC;IACD,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAAC,mBAAmB,CAAC,EAAE,CAAC;QACjD,MAAM,IAAI,KAAK,CAAC,uFAAuF,CAAC,CAAC;IAC3G,CAAC;IACD,MAAM,KAAK,GAAG,MAAM,IAAA,mBAAQ,EAAC,IAAI,CAAC,CAAC;IACnC,IAAA,yBAAkB,EAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IAChC,IAAI,KAAK,CAAC,YAAY,CAAC,CAAC,CAAC,KAAK,KAAK,CAAC,MAAM,EAAE,CAAC;QAC3C,MAAM,IAAI,KAAK,CAAC,yCAAyC,CAAC,CAAC;IAC7D,CAAC;IACD,MAAM,IAAI,GAAG,IAAI,QAAQ,EAAE,CAAC;IAC5B,IAAI,CAAC,GAAG,CAAC,qBAAqB,EAAE,mBAAmB,CAAC,WAAW,EAAE,CAAC,CAAC;IACnE,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,IAAI,IAAI,CAAC,CAAC,IAAI,UAAU,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,IAAI,EAAE,mBAAmB,EAAE,CAAC,EAAE,IAAA,oBAAQ,EAAC,IAAI,CAAC,CAAC,CAAC;IACnG,OAAO,cAAQ,CAAC,cAAc,CAAC,WAAW,CAAC,CAAC,aAAa,CACvD,2BAA2B,MAAM,cAAc,EAAE,IAAI,EAAE,6BAA6B,CACrF,CAAC;AACJ,CAAC;AAEY,QAAA,oBAAoB,GAC/B,mGAAmG;IACnG,+HAA+H;IAC/H,+IAA+I,CAAC;AAElJ,uHAAuH;AACvH,SAAgB,sBAAsB,CAAC,QAAgB;IACrD,OAAO,oCAAoC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,GAAG,QAAQ,SAAS,4BAAoB,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC;AACrH,CAAC"}

package/dist/index.js

@@ -46,6 +46,7 @@ const commands_1 = require("./sceneHlod/commands");
 const placementRequest_1 = require("./placementRequest");
 const bundle_1 = require("./bundle");
 const avatarMeshReplacement_1 = require("./avatarMeshReplacement");
+const itemThumbnail_1 = require("./itemThumbnail");
 const addOnPackageVersion_1 = require("./addOnPackageVersion");
 const node_child_process_1 = require("node:child_process");
 const node_fs_1 = require("node:fs");
@@ -1545,7 +1546,51 @@ item
             console.log(`✔ Corrected avatar ${result.item.id}. Existing ownership and previous rendition bytes are preserved.`);
     }
     catch (error) {
-        fail(error instanceof lib_1.ApiError ? error.render() : String(error));
+        fail(error instanceof lib_1.ApiError ? (0, avatarMeshReplacement_1.withPackageVersionHint)(error.render()) : String(error));
+    }
+});
+// Refresh or replace the thumbnail of an ALREADY-published item. Unrelated to the top-level `thumbnail` command
+// (worlds, by slug): items are addressed by UUID and the server owns the render.
+const itemThumbnail = item
+    .command('thumbnail')
+    .description('Refresh or replace a published item\'s thumbnail (by item UUID; for a world\'s cover use `helix thumbnail set`)');
+itemThumbnail
+    .command('refresh')
+    .description('Re-render the canonical thumbnail from the item\'s active Package Version with the standard server renderer (owner or admin)')
+    .argument('<item-id>', 'published item UUID')
+    .option('--force', 're-render even when the stored thumbnail already matches the current renderer and source')
+    .option('--dry-run', 'report what would change without writing anything')
+    .option('--json', 'print the authoritative server receipt')
+    .action(async (itemId, opts) => {
+    try {
+        const result = await (0, itemThumbnail_1.refreshItemThumbnail)(itemId, { force: opts.force, dryRun: opts.dryRun }, requireAuth());
+        if (opts.json)
+            console.log(JSON.stringify(result, null, 2));
+        else
+            for (const line of (0, itemThumbnail_1.renderItemThumbnailResult)(result))
+                console.log(line);
+    }
+    catch (error) {
+        fail(`✖ ${(0, itemThumbnail_1.describeThumbnailError)(error, itemId)}`);
+    }
+});
+itemThumbnail
+    .command('set')
+    .description('Upload your own thumbnail image (png, jpg, or webp) for a published item; moderated, and it stays until you refresh with --force')
+    .argument('<item-id>', 'published item UUID')
+    .argument('<image>', 'png / jpg / webp file')
+    .option('--json', 'print the authoritative server receipt')
+    .action(async (itemId, image, opts) => {
+    try {
+        const result = await (0, itemThumbnail_1.setItemThumbnail)(itemId, (0, node_path_1.resolve)(image), requireAuth());
+        if (opts.json)
+            console.log(JSON.stringify(result, null, 2));
+        else
+            for (const line of (0, itemThumbnail_1.renderItemThumbnailResult)(result))
+                console.log(line);
+    }
+    catch (error) {
+        fail(`✖ ${(0, itemThumbnail_1.describeThumbnailError)(error, itemId)}`);
     }
 });
 // Ship a fix to an already-published item WITHOUT churning it onto a new id: