@helix3/helix-cli 0.1.18-helix3.277 → 0.1.18-helix3.278

package/dist/addOnPackageVersion.d.ts

@@ -0,0 +1,47 @@
+import type { CliCredentials } from './config';
+export type PackagePin = {
+    packageId: string;
+    version: string;
+    manifestCid: string;
+};
+export type PublishAddOnPackageVersionOptions = {
+    reason: string;
+    notes?: string;
+    expectedCurrentVersionId?: string;
+    updateId?: string;
+    /** Bounded wait for the uploaded mesh to clear verify/optimize and reach `ready`. */
+    assetReadyTimeoutMs?: number;
+    onProgress?: (message: string) => void;
+};
+export type PublishAddOnPackageVersionResult = {
+    itemId: string;
+    revision: number;
+    packagePin: PackagePin;
+    previousRevision: number;
+    previousPackagePin: PackagePin;
+    updateId?: string;
+    [key: string]: unknown;
+};
+/**
+ * Ship a corrected mesh onto an ALREADY-PUBLISHED character add-on, in place:
+ * same item id, same owner, same serial, same listings and distributions —
+ * every existing owner picks up the new geometry at their next spawn/session
+ * start. Two backend steps, in sequence:
+ *
+ *   1. The ordinary asset door: `POST :id/assets` (presign) → PUT the bytes →
+ *      `POST :id/assets/:assetId/finalize` — the exact verify/optimize
+ *      pipeline `helix item publish` runs on a brand-new item. This function
+ *      polls the asset's status afterward, because finalize only STARTS that
+ *      pipeline; it does not wait for it.
+ *   2. `POST :id/add-on-package/versions` — seals that now-Ready GLB as a new
+ *      Version of the item's own Continuum Package and moves the item's
+ *      pointer through the platform's real, audited, revision-checked
+ *      version-update path (the same one Skylark/Ocean Drive republish
+ *      through). Refused (409) if the new geometry breaks the compatibility
+ *      contract (slot removed, contract changed, …) — that is not a bug in
+ *      this command, it means the change is not a valid update to this item.
+ *
+ * There is no local dry-run: everything here is a server-verified round trip,
+ * same as `helix item publish`.
+ */
+export declare function publishAddOnPackageVersion(itemId: string, file: string, options: PublishAddOnPackageVersionOptions, credentials: CliCredentials): Promise<PublishAddOnPackageVersionResult>;

package/dist/addOnPackageVersion.js

@@ -0,0 +1,93 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.publishAddOnPackageVersion = publishAddOnPackageVersion;
+const promises_1 = require("node:fs/promises");
+const node_path_1 = require("node:path");
+const api_1 = require("./api");
+const item_1 = require("./item");
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const MAX_ADDON_WEB_GLB_BYTES = 64 * 1024 * 1024; // mirrors the backend's own ceiling for this lane
+const DEFAULT_ASSET_READY_TIMEOUT_MS = 180_000;
+const ASSET_POLL_INTERVAL_MS = 2_000;
+/**
+ * Ship a corrected mesh onto an ALREADY-PUBLISHED character add-on, in place:
+ * same item id, same owner, same serial, same listings and distributions —
+ * every existing owner picks up the new geometry at their next spawn/session
+ * start. Two backend steps, in sequence:
+ *
+ *   1. The ordinary asset door: `POST :id/assets` (presign) → PUT the bytes →
+ *      `POST :id/assets/:assetId/finalize` — the exact verify/optimize
+ *      pipeline `helix item publish` runs on a brand-new item. This function
+ *      polls the asset's status afterward, because finalize only STARTS that
+ *      pipeline; it does not wait for it.
+ *   2. `POST :id/add-on-package/versions` — seals that now-Ready GLB as a new
+ *      Version of the item's own Continuum Package and moves the item's
+ *      pointer through the platform's real, audited, revision-checked
+ *      version-update path (the same one Skylark/Ocean Drive republish
+ *      through). Refused (409) if the new geometry breaks the compatibility
+ *      contract (slot removed, contract changed, …) — that is not a bug in
+ *      this command, it means the change is not a valid update to this item.
+ *
+ * There is no local dry-run: everything here is a server-verified round trip,
+ * same as `helix item publish`.
+ */
+async function publishAddOnPackageVersion(itemId, file, options, credentials) {
+    if (!UUID_RE.test(itemId))
+        throw new Error('Item ID must be a UUID.');
+    const reason = options.reason?.trim() ?? '';
+    if (!reason || reason.length > 500) {
+        throw new Error('--reason is required (1-500 characters) and lands in the audit ledger.');
+    }
+    const bytes = await (0, promises_1.readFile)(file);
+    (0, item_1.assertLooksLikeGlb)(bytes, file);
+    if (bytes.length > MAX_ADDON_WEB_GLB_BYTES) {
+        throw new Error(`"${file}" is ${(bytes.length / (1024 * 1024)).toFixed(1)} MiB; an add-on's web GLB must be at most ${MAX_ADDON_WEB_GLB_BYTES / (1024 * 1024)} MiB.`);
+    }
+    const progress = options.onProgress ?? (() => { });
+    const api = api_1.HelixApi.forCredentials(credentials);
+    const filename = (0, node_path_1.basename)(file);
+    const mimeType = 'model/gltf-binary';
+    progress('Requesting a presigned upload for the corrected mesh…');
+    const presign = await api.requestItem('POST', `/api/v1/universal-items/${itemId}/assets`, {
+        rendition: 'web',
+        filename,
+        mimeType,
+        sizeBytes: bytes.length,
+    });
+    if (!presign.uploadUrl)
+        throw new Error('Server did not return an upload URL for the web asset.');
+    progress('Uploading the mesh…');
+    await (0, api_1.uploadToTicket)(presign.uploadUrl, Buffer.from(bytes), mimeType);
+    progress('Finalizing the upload (verify → optimize → thumbnail)…');
+    await api.requestItem('POST', `/api/v1/universal-items/${itemId}/assets/${presign.id}/finalize`, { sizeBytes: bytes.length });
+    progress('Waiting for the pipeline to mark the mesh ready…');
+    const ready = await waitForAssetReady(api, itemId, presign.id, options.assetReadyTimeoutMs ?? DEFAULT_ASSET_READY_TIMEOUT_MS);
+    if (ready.status !== 'ready') {
+        throw new Error(`Upload finished but the pipeline left it "${ready.status}", not "ready" — it will not be sealed into a new Package Version. Check the item's assets for the rejection reason.`);
+    }
+    progress('Sealing the new Package Version and publishing it to every owner…');
+    const body = { reason };
+    if (options.notes !== undefined)
+        body.notes = options.notes;
+    if (options.expectedCurrentVersionId !== undefined)
+        body.expectedCurrentVersionId = options.expectedCurrentVersionId;
+    if (options.updateId !== undefined)
+        body.updateId = options.updateId;
+    return api.request('POST', `/api/v1/universal-items/${itemId}/add-on-package/versions`, body);
+}
+async function waitForAssetReady(api, itemId, assetId, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+        const assets = await api.request('GET', `/api/v1/universal-items/${itemId}/assets`);
+        const row = assets.find((a) => a.id === assetId);
+        if (!row)
+            throw new Error(`Asset ${assetId} disappeared from ${itemId}'s asset list.`);
+        if (row.status === 'ready' || row.status === 'rejected' || row.status === 'failed')
+            return row;
+        if (Date.now() >= deadline) {
+            throw new Error(`Timed out after ${Math.round(timeoutMs / 1000)}s waiting for asset ${assetId} to leave "${row.status}".`);
+        }
+        await new Promise((resolve) => setTimeout(resolve, ASSET_POLL_INTERVAL_MS));
+    }
+}
+//# sourceMappingURL=addOnPackageVersion.js.map

package/dist/addOnPackageVersion.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"addOnPackageVersion.js","sourceRoot":"","sources":["../src/addOnPackageVersion.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -39,6 +39,7 @@ const commands_1 = require("./sceneHlod/commands");
 const placementRequest_1 = require("./placementRequest");
 const bundle_1 = require("./bundle");
 const avatarMeshReplacement_1 = require("./avatarMeshReplacement");
+const addOnPackageVersion_1 = require("./addOnPackageVersion");
 const node_child_process_1 = require("node:child_process");
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
@@ -1207,6 +1208,49 @@ item
         fail(error instanceof lib_1.ApiError ? error.render() : String(error));
     }
 });
+// Ship a fix to an already-published item WITHOUT churning it onto a new id:
+// same item, same owner, same serial, same listings/distributions, every
+// existing owner picks up the new geometry at their next spawn. Character
+// add-ons only today — the backend's `add-on-package/versions` lane exists
+// because an add-on's Continuum Package is built FROM the item's own uploaded
+// mesh, unlike a vehicle or Scene Package, which are authored and sealed
+// independently and update through the generic (not-yet-CLI-exposed)
+// `POST :itemId/versions`. `helix item delist` is the OTHER lane here and does
+// something different: it takes an item off browse/marketplace for good,
+// rather than shipping owners an update.
+item
+    .command('publish-version')
+    .description('Ship a corrected mesh onto an already-published character add-on, IN PLACE — new Package Version, same item id/owner/listings; every existing owner gets it next spawn')
+    .argument('<item-id>', 'existing, already-published character add-on item UUID')
+    .argument('<file>', 'corrected mesh (binary glTF, .glb)')
+    .requiredOption('--reason <text>', 'required, lands in the audit ledger (e.g. "fixed poke-through on the left cuff")')
+    .option('--notes <text>', 'optional creator-facing changelog note')
+    .option('--expected-current-version-id <uuid>', 'refuse if the item has moved off this Package Version since you last read it')
+    .option('--update-id <uuid>', 'idempotency key — retrying with the same id never double-publishes')
+    .option('--json', 'machine-readable output')
+    .action(async (itemId, file, opts) => {
+    const creds = requireAuth();
+    try {
+        const result = await (0, addOnPackageVersion_1.publishAddOnPackageVersion)(itemId, (0, node_path_1.resolve)(file), {
+            reason: opts.reason,
+            notes: opts.notes,
+            expectedCurrentVersionId: opts.expectedCurrentVersionId,
+            updateId: opts.updateId,
+            onProgress: (message) => !opts.json && console.log(message),
+        }, creds);
+        if (opts.json) {
+            console.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        console.log(`✔ Published a new Version of ${itemId} — revision ${result.previousRevision} → ${result.revision}`);
+        console.log(`  package: ${result.packagePin.packageId}@${result.packagePin.version}`);
+        console.log(`  previous: ${result.previousPackagePin.packageId}@${result.previousPackagePin.version}`);
+        console.log('  same item id, same owner(s); existing owners see the change at their next spawn/session start.');
+    }
+    catch (error) {
+        fail(error instanceof lib_1.ApiError ? error.render() : `✖ ${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