@hypersoniclabs/helix-cli 0.1.7 → 0.1.24-helix3.438

package/dist/item.js

@@ -0,0 +1,892 @@
+"use strict";
+// Pure, network-free helpers behind `helix item …` — the Character-Creator slot
+// table, the kind rules, the file sniffing, and the payload builder. Kept apart
+// from the HTTP flow in lib.ts on purpose (the same split as
+// mediaContentTypeFromExtension / assertMediaSizeOk / assertMediaSlotWritable):
+// every rule below is testable without mocking a server.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TUNE_ONLY_VEHICLE_SLOT_TYPES = exports.MAX_CLIP_SET_OPS = exports.MAX_ADD_ON_OPS = exports.CLIP_SET_SLOT_TYPES = exports.MESH_CONTENT_TYPE = exports.UPLOADABLE_ITEM_KINDS = exports.CC_GENDERS = exports.CC_WEARABLE_SLOTS = exports.CC_WEARABLE_SLOT_GROUPS = void 0;
+exports.isCcWearableSlot = isCcWearableSlot;
+exports.isCcGender = isCcGender;
+exports.ccGendersAreRequiredForKind = ccGendersAreRequiredForKind;
+exports.ccGendersAreAllowedForKind = ccGendersAreAllowedForKind;
+exports.parseGenders = parseGenders;
+exports.renderCcGenderList = renderCcGenderList;
+exports.assertCcGenders = assertCcGenders;
+exports.isUploadableItemKind = isUploadableItemKind;
+exports.normalizeItemKind = normalizeItemKind;
+exports.describeUploadableItemKinds = describeUploadableItemKinds;
+exports.ccSlotIsRequiredForKind = ccSlotIsRequiredForKind;
+exports.ccSlotIsAllowedForKind = ccSlotIsAllowedForKind;
+exports.renderCcSlotTable = renderCcSlotTable;
+exports.assertCcSlot = assertCcSlot;
+exports.meshContentTypeFromExtension = meshContentTypeFromExtension;
+exports.thumbnailContentTypeFromExtension = thumbnailContentTypeFromExtension;
+exports.assertLooksLikeGlb = assertLooksLikeGlb;
+exports.meshSizeWarning = meshSizeWarning;
+exports.maxOpsForSlot = maxOpsForSlot;
+exports.isTuneOnlyVehiclePart = isTuneOnlyVehiclePart;
+exports.isMeshlessItem = isMeshlessItem;
+exports.parseJsonOrFile = parseJsonOrFile;
+exports.parseJsonObjectOrFile = parseJsonObjectOrFile;
+exports.parseJsonArrayOrFile = parseJsonArrayOrFile;
+exports.validateAddOnContract = validateAddOnContract;
+exports.parseTags = parseTags;
+exports.buildItemPayload = buildItemPayload;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const distribution_1 = require("./distribution");
+// ---------------------------------------------------------------------------
+// Character-Creator cosmetic slots
+// ---------------------------------------------------------------------------
+//
+// !! MIRROR — KEEP IN LOCKSTEP WITH THE BACKEND !!
+//
+//   AUTHORITY: helix-backend-api → src/universal-items/cc-wearable-slot.ts
+//              (`CC_WEARABLE_SLOTS`). The UE Character Creator taxonomy is the
+//              origin; the backend is the copy every client must agree with.
+//
+// This list is a LOCAL FAST PATH, never the authority. It exists so a bad tag is
+// caught before a 30 MB mesh is uploaded and a publish fee is charged — nothing
+// more. Two properties keep a stale copy harmless:
+//
+//   1. the CLI never invents a tag: `--slot` is matched EXACTLY against this
+//      table, so a typo fails locally with the full list;
+//   2. the server is always the last word: its 400 enumerates every valid tag
+//      and is surfaced verbatim (ApiError.render()), so a CLI missing a
+//      NEWLY-added slot tells the user the real list instead of guessing.
+//
+// When the backend adds or renames a slot, edit THIS table in the same PR wave.
+// `item.spec.ts` pins the exact tag list, so any edit is a deliberate,
+// reviewed diff rather than a silent drift.
+//
+// (Why not import it from @hypersoniclabs/helix-manifest, the one package this
+// CLI and the backend already share? See docs/../PR notes: helix-manifest is the
+// Instant *world bundle* contract — the backend's universal-items module has no
+// dependency edge to it — and the CLI's publish script rewrites
+// `file:../helix-manifest` to `^<latest PUBLISHED version>`, so a CLI release
+// that beat a manifest release would compile locally and ship with the export
+// `undefined` at runtime. A silently-undefined validation table is worse than a
+// visibly-mirrored one.)
+/** The five CC slot groups, in the order `helix item list-slots` prints them. */
+exports.CC_WEARABLE_SLOT_GROUPS = [
+    {
+        group: 'Clothing',
+        summary: 'wearable garments',
+        slots: [
+            'Cosmetic.Slot.Clothing.Top',
+            'Cosmetic.Slot.Clothing.Bottoms',
+            'Cosmetic.Slot.Clothing.Set',
+            'Cosmetic.Slot.Clothing.Backpack',
+            'Cosmetic.Slot.Clothing.Socks',
+            'Cosmetic.Slot.Clothing.Shoes',
+            'Cosmetic.Slot.Clothing.Underwear.Top',
+            'Cosmetic.Slot.Clothing.Underwear.Bottom',
+            'Cosmetic.Slot.Clothing.Underwear.Leg',
+        ],
+    },
+    {
+        group: 'Accessory',
+        summary: 'attached props, grouped by body zone',
+        slots: [
+            'Cosmetic.Slot.Accessory.Head.Hat',
+            'Cosmetic.Slot.Accessory.Face.Mask',
+            'Cosmetic.Slot.Accessory.Face.Eyewear',
+            'Cosmetic.Slot.Accessory.Neck.Necklace',
+            'Cosmetic.Slot.Accessory.Ears.Earrings',
+            'Cosmetic.Slot.Accessory.Hands.Gloves',
+            'Cosmetic.Slot.Accessory.Hands.Nails',
+        ],
+    },
+    {
+        group: 'Appearance',
+        summary: 'non-mesh visual layers',
+        slots: [
+            'Cosmetic.Slot.Appearance.Hair.Main',
+            'Cosmetic.Slot.Appearance.Hair.Facial.Beard',
+            'Cosmetic.Slot.Appearance.Hair.Facial.Mustache',
+            'Cosmetic.Slot.Appearance.Eyes.Eyebrows',
+            'Cosmetic.Slot.Appearance.Eyes.Eyelashes',
+            'Cosmetic.Slot.Appearance.Eyes.Iris',
+            'Cosmetic.Slot.Appearance.Skin.BodyTattoo',
+            'Cosmetic.Slot.Appearance.Skin.FaceTattoo',
+            'Cosmetic.Slot.Appearance.Makeup.Lipstick',
+            'Cosmetic.Slot.Appearance.Makeup.Eyeliner',
+            'Cosmetic.Slot.Appearance.Makeup.Eyeshadow',
+            'Cosmetic.Slot.Appearance.Makeup.Blush',
+        ],
+    },
+    {
+        group: 'Body',
+        summary: 'modular base meshes',
+        slots: [
+            'Cosmetic.Slot.Body.Head',
+            'Cosmetic.Slot.Body.Upper',
+            'Cosmetic.Slot.Body.Lower',
+            'Cosmetic.Slot.Body.Hands',
+            'Cosmetic.Slot.Body.Feet',
+        ],
+    },
+    {
+        group: 'Custom',
+        summary: 'a custom full-body mesh that overrides the modular body',
+        slots: ['Cosmetic.Slot.Custom'],
+    },
+];
+/** Every CC slot tag, flattened in group order. Derived — never a second literal. */
+exports.CC_WEARABLE_SLOTS = exports.CC_WEARABLE_SLOT_GROUPS.flatMap((g) => g.slots);
+const CC_WEARABLE_SLOT_SET = new Set(exports.CC_WEARABLE_SLOTS);
+/** True if `tag` is a known CC wearable slot tag. Casing is EXACT. */
+function isCcWearableSlot(tag) {
+    return typeof tag === 'string' && CC_WEARABLE_SLOT_SET.has(tag);
+}
+// ---------------------------------------------------------------------------
+// Character-Creator genders
+// ---------------------------------------------------------------------------
+//
+// !! MIRROR — KEEP IN LOCKSTEP WITH THE BACKEND !!
+//
+//   AUTHORITY: helix-backend-api → src/universal-items/cc-gender.ts
+//              (`CC_GENDERS`), stored as `universal_items.cc_genders` and sent
+//              on the wire as `genders`. The UE `EHCharacterCosmeticsGender`
+//              enum is the origin; the backend is the copy every client agrees
+//              with.
+//
+// Same contract as the slot table above: a LOCAL FAST PATH so a bad value fails
+// before a mesh is uploaded and a non-refundable publish fee is charged, never
+// the authority. `item.spec.ts` pins the exact values so drift arrives only as a
+// reviewed diff.
+//
+// TWO values, and there is NO third. Unreal's enum is Male/Female (its `None` is
+// documented as internal, and the legacy `All` is gone), so there is no
+// "unisex"/"fits everyone" token to reach for — a garment that fits every body
+// declares EVERY gender it fits: male,female. The CLI deliberately does NOT
+// invent a `both`/`all` alias: the moment the CLI's vocabulary diverges from the
+// wire's, the server's own error messages (which name `male` and `female`) stop
+// matching what the creator typed. `both` is instead rejected BY NAME with the
+// spelling that works.
+//
+// A single row carrying {male, female} is the deliberate web equivalent of
+// Unreal's two entries sharing one mesh: the web runtime ships ONE GLB worn by
+// every body, so a scalar would force the row to lie about one of the two
+// renditions.
+exports.CC_GENDERS = ['male', 'female'];
+const CC_GENDER_SET = new Set(exports.CC_GENDERS);
+/** True if `value` is a known CC gender. Casing is EXACT (lowercase). */
+function isCcGender(value) {
+    return typeof value === 'string' && CC_GENDER_SET.has(value);
+}
+/** A wearable cannot be exported to the Character Creator without a gender. */
+function ccGendersAreRequiredForKind(kind) {
+    return kind === 'wearable';
+}
+/**
+ * Only wearables (required) and avatars (optional — an avatar is a
+ * `Cosmetic.Slot.Body.*` modular mesh, gendered like anything else) are authored
+ * per gender. A gender on a home item is meaningless and is rejected rather than
+ * silently stored. Deliberately the SAME kind rule as the slot.
+ */
+function ccGendersAreAllowedForKind(kind) {
+    return kind === 'wearable' || kind === 'avatar';
+}
+/**
+ * Misspellings that mean "every body", each mapped to the phrasing that works.
+ * These exist because the value a creator reaches for first does not exist, and
+ * a bare "unknown gender" error would leave them guessing at a third token
+ * instead of learning that the answer is to name both.
+ */
+const NO_SUCH_UNIVERSAL_GENDER = new Set([
+    'both',
+    'all',
+    'any',
+    'unisex',
+    'neutral',
+    'none',
+    'universal',
+]);
+/**
+ * Split a `--gender male,female` value the way `parseTags` splits tags: trimmed,
+ * empties dropped, deduped, then ordered by `CC_GENDERS` so `female,male` and
+ * `male,female` produce the SAME array. Two publishes that mean the same thing
+ * must send the same value, or a `genders = {male,female}` filter silently
+ * misses half the catalogue.
+ *
+ * Values are NOT lowercased — mirroring the backend's `normalizeCcGenders`.
+ * `Male` is not a CC gender, and quietly repairing it here would hide a client
+ * sending UE's enum casing verbatim. Unknown values are kept so the validator
+ * can reject them BY NAME.
+ */
+function parseGenders(value) {
+    const seen = new Set();
+    for (const raw of value.split(',')) {
+        const part = raw.trim();
+        if (part)
+            seen.add(part);
+    }
+    const known = exports.CC_GENDERS.filter((g) => seen.has(g));
+    const unknown = [...seen].filter((v) => !isCcGender(v));
+    return [...known, ...unknown];
+}
+/** The valid genders, rendered for a terminal (also printed by `list-slots`). */
+function renderCcGenderList() {
+    return (`${exports.CC_GENDERS.join(', ')} (lowercase, comma-separated for more than one)\n` +
+        '  A garment that fits every body declares BOTH: --gender male,female.\n' +
+        '  There is no "unisex"/"all"/"both" value — Unreal requires a gender on\n' +
+        '  every entry, accessories and tattoos included.');
+}
+/**
+ * Validate the (kind, genders) pair the way the backend does, and throw the same
+ * three failures. Mirrors `validateCcGendersForKind` in helix-backend-api.
+ *
+ * `undefined` and `[]` are the SAME thing — "no genders declared" — because the
+ * column is `NOT NULL DEFAULT '{}'`: an omitted field and an explicit empty list
+ * both land as `{}` server-side and must fail identically for a wearable.
+ */
+function assertCcGenders(kind, genders) {
+    const list = parseGenders((genders ?? []).join(','));
+    const unknown = list.filter((g) => !isCcGender(g));
+    if (unknown.length > 0) {
+        // A creator who typed "both"/"unisex" does not need the vocabulary — they
+        // need the ONE sentence that says the value they want does not exist and
+        // what to write instead. Repeating the full list under it buries that.
+        const universal = unknown.find((g) => NO_SUCH_UNIVERSAL_GENDER.has(g.toLowerCase()));
+        if (universal !== undefined) {
+            throw new Error(`There is no "${universal}" Character-Creator gender. A garment that fits every ` +
+                'body names every gender it fits: --gender male,female.');
+        }
+        throw new Error(`Unknown Character-Creator gender ${unknown.map((g) => `"${g}"`).join(', ')} ` +
+            '(matching is exact, and lowercase).\n' +
+            `Valid genders: ${renderCcGenderList()}`);
+    }
+    if (list.length === 0 && ccGendersAreRequiredForKind(kind)) {
+        throw new Error('A wearable must declare the Character-Creator gender(s) it is authored for — pass --gender.\n' +
+            `Valid genders: ${renderCcGenderList()}`);
+    }
+    if (list.length > 0 && !ccGendersAreAllowedForKind(kind)) {
+        throw new Error(`Character-Creator genders are meaningless for kind "${kind}" — only wearables ` +
+            '(required) and avatars (optional) are authored per gender. Drop --gender.');
+    }
+}
+// ---------------------------------------------------------------------------
+// Item kinds
+// ---------------------------------------------------------------------------
+/**
+ * The kinds `POST /universal-items/upload` accepts. Everything else in the
+ * backend's UniversalItemKind enum (emote / prop / bundle / achievement) is not
+ * an uploadable mesh and is rejected server-side, so the CLI never offers it.
+ */
+exports.UPLOADABLE_ITEM_KINDS = [
+    'wearable',
+    'avatar',
+    // Add-ons use the same verified mesh upload path as wearables. Their
+    // compatibility contract is carried by `fits`/`ops`, not by a CC slot.
+    'add_on',
+    'home_item',
+    'home_shell',
+    // A vehicle verifies and optimises on exactly the home-item path server-side
+    // (static mesh, same limits). It is listed here because the alternative is
+    // what actually happened: with no vehicle kind to publish into, the three
+    // hero vehicles were published as `home_item` and shoppers saw cars filed
+    // under Furniture and labelled "Prop".
+    'vehicle',
+];
+function isUploadableItemKind(k) {
+    return (typeof k === 'string' &&
+        exports.UPLOADABLE_ITEM_KINDS.includes(k));
+}
+/**
+ * Friendly, CURRENT product names for the two wire values above whose names
+ * predate the rename (see helixgame.com's `lib/items/types.ts` label map —
+ * `home_item: "Props"`, `home_shell: "Homes"`, CH-1638). This is display and
+ * input-vocabulary ONLY: the wire value a creator's `home_item`/`home_shell`
+ * item is stored and served under is unchanged, and so is
+ * `UniversalItemKind` in helix-backend-api (which separately, and
+ * deliberately, ALSO has a distinct `Prop = 'prop'` kind for art/collectible
+ * items — do not confuse the two; this alias never reaches the wire as
+ * anything but `home_item` / `home_shell`).
+ */
+const ITEM_KIND_LABELS = {
+    wearable: 'wearable',
+    avatar: 'avatar',
+    add_on: 'add_on',
+    home_item: 'prop',
+    home_shell: 'home',
+    vehicle: 'vehicle',
+};
+/**
+ * Friendly-name → wire-value aliases accepted anywhere a `--kind` is typed.
+ * The wire values (`home_item`, `home_shell`, …) remain valid input too —
+ * back-compat for scripts/docs already using them.
+ */
+const ITEM_KIND_ALIASES = {
+    prop: 'home_item',
+    home: 'home_shell',
+};
+/**
+ * Resolve a user-typed `--kind` value (current product name, legacy wire
+ * value, or garbage) to the wire value the backend's `UniversalItemKind`
+ * expects — the ONLY thing that ever leaves this function is one of
+ * `UPLOADABLE_ITEM_KINDS`'s existing members, or the input unchanged if it
+ * matches neither an alias nor a wire value (left for `isUploadableItemKind`
+ * to reject with the full accepted list).
+ */
+function normalizeItemKind(value) {
+    return ITEM_KIND_ALIASES[value] ?? value;
+}
+/**
+ * Human-facing list of accepted `--kind` values, leading with the current
+ * product name and showing the underlying wire value alongside it (so
+ * `grep`ing for `home_item`/`home_shell` still finds this string). Used by
+ * the `--kind` option help and every "unsupported kind" error so the two
+ * never drift apart.
+ */
+function describeUploadableItemKinds() {
+    return exports.UPLOADABLE_ITEM_KINDS.map((wire) => {
+        const label = ITEM_KIND_LABELS[wire];
+        return label === wire ? wire : `${label} (${wire})`;
+    }).join(' | ');
+}
+/** A wearable cannot be equipped without a slot, so it cannot be published without one. */
+function ccSlotIsRequiredForKind(kind) {
+    return kind === 'wearable';
+}
+/**
+ * Only wearables (required) and avatars (optional — a full-body avatar maps to
+ * `Cosmetic.Slot.Body.*` or `Cosmetic.Slot.Custom`) occupy a cosmetic slot. A
+ * slot on a home item is meaningless and is rejected rather than stored.
+ */
+function ccSlotIsAllowedForKind(kind) {
+    return kind === 'wearable' || kind === 'avatar';
+}
+/** The grouped tag list, rendered for a terminal (also the body of `list-slots`). */
+function renderCcSlotTable() {
+    return exports.CC_WEARABLE_SLOT_GROUPS.map((g) => `${g.group} — ${g.summary}\n${g.slots.map((s) => `  ${s}`).join('\n')}`).join('\n\n');
+}
+/**
+ * Validate the (kind, slot) pair the way the backend does, and throw the same
+ * three failures with the full tag list attached. Mirrors
+ * `validateCcSlotForKind` in helix-backend-api.
+ */
+function assertCcSlot(kind, slot) {
+    const tag = slot === undefined || slot === null || slot === '' ? null : slot;
+    if (tag !== null && !isCcWearableSlot(tag)) {
+        throw new Error(`Unknown Character-Creator slot tag "${tag}" (matching is exact, including case).\n` +
+            `Valid tags:\n${renderCcSlotTable()}`);
+    }
+    if (tag === null && ccSlotIsRequiredForKind(kind)) {
+        throw new Error('A wearable must declare the Character-Creator slot it occupies — pass --slot.\n' +
+            `Valid tags:\n${renderCcSlotTable()}`);
+    }
+    if (tag !== null && !ccSlotIsAllowedForKind(kind)) {
+        throw new Error(`A Character-Creator cosmetic slot is meaningless for kind "${kind}" — only ` +
+            'wearables (required) and avatars (optional) occupy one. Drop --slot.');
+    }
+}
+// ---------------------------------------------------------------------------
+// File sniffing — mesh + thumbnail
+// ---------------------------------------------------------------------------
+exports.MESH_CONTENT_TYPE = 'model/gltf-binary';
+const THUMBNAIL_CONTENT_TYPES = {
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.webp': 'image/webp',
+};
+const lowerExtension = (file) => {
+    const base = file.slice(Math.max(file.lastIndexOf('/'), file.lastIndexOf('\\')) + 1);
+    const dot = base.lastIndexOf('.');
+    return dot <= 0 ? '' : base.slice(dot).toLowerCase();
+};
+/**
+ * Content type for the `mesh` part. Binary glTF only — a `.gltf` is a JSON
+ * document whose buffers/textures live in sibling files, so it cannot be
+ * uploaded as one part at all; say that instead of letting the server guess.
+ */
+function meshContentTypeFromExtension(file) {
+    const ext = lowerExtension(file);
+    if (ext === '.glb')
+        return exports.MESH_CONTENT_TYPE;
+    if (ext === '.gltf') {
+        throw new Error(`"${file}" is a .gltf — a JSON glTF references its buffers and textures as separate ` +
+            'files, so it cannot be uploaded as a single mesh. Export (or pack) it as a .glb.');
+    }
+    throw new Error(`unsupported mesh file type "${ext || file}" — upload a binary glTF (.glb)`);
+}
+/** Content type for the optional `thumbnail` part — png/jpg/jpeg/webp only. */
+function thumbnailContentTypeFromExtension(file) {
+    const ext = lowerExtension(file);
+    const contentType = THUMBNAIL_CONTENT_TYPES[ext];
+    if (!contentType) {
+        throw new Error(`unsupported thumbnail file type "${ext || file}" — use png, jpg/jpeg, or webp`);
+    }
+    return contentType;
+}
+/**
+ * Prove the bytes really are a binary glTF before spending an upload on them:
+ * a GLB starts with the ASCII magic `glTF` followed by a uint32 version. Catches
+ * the two mistakes a renamed export makes — a JSON .gltf saved as .glb, and a
+ * zip/FBX with the extension swapped.
+ */
+function assertLooksLikeGlb(bytes, file) {
+    if (bytes.byteLength === 0)
+        throw new Error(`"${file}" is empty`);
+    if (bytes.byteLength < 12) {
+        throw new Error(`"${file}" is too small to be a binary glTF (${bytes.byteLength} bytes)`);
+    }
+    const magic = String.fromCharCode(bytes[0], bytes[1], bytes[2], bytes[3]);
+    if (magic !== 'glTF') {
+        throw new Error(`"${file}" is not a binary glTF — it starts with ${JSON.stringify(magic)}, not "glTF". ` +
+            'Re-export as .glb (binary), not .gltf (JSON) or a zipped archive.');
+    }
+    const version = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength).getUint32(4, true);
+    if (version !== 2) {
+        throw new Error(`"${file}" is glTF version ${version}; HELIX accepts glTF 2.0 (.glb).`);
+    }
+}
+/**
+ * ADVISORY mesh-size ceilings — the backend's SHIPPED DEFAULTS, mirrored so a
+ * 300 MB export fails in a second instead of after a long upload.
+ *
+ * These are advisory on purpose and produce a WARNING, never a hard failure:
+ * every one of them is an env-overridable server setting
+ * (`WEARABLE_MAX_FILE_BYTES`, `AVATAR_MAX_FILE_BYTES`, …), so a CLI that
+ * REFUSED at these numbers would be wrong the moment an environment raises one.
+ * The server owns the verdict; this only tells you early what it will probably
+ * say — and that `--allow-oversize` exists.
+ */
+const ADVISORY_MAX_MESH_BYTES = {
+    wearable: 6 * 1024 * 1024,
+    avatar: 24 * 1024 * 1024,
+    // The backend deliberately applies the wearable ceiling: several add-ons
+    // can be mounted on one already-rendered host.
+    add_on: 6 * 1024 * 1024,
+    home_item: 12 * 1024 * 1024,
+    home_shell: 12 * 1024 * 1024,
+    // Mirrors VEHICLE_MAX_FILE_BYTES (helix-backend-api src/config.ts): the server
+    // verifies a vehicle through vehicleLimits(), 16 MiB — not the 8 MiB furniture
+    // ceiling a vehicle used to inherit. Advising a different number here makes the
+    // CLI's early warning disagree with the verdict that follows.
+    vehicle: 16 * 1024 * 1024,
+};
+const mib = (bytes) => `${(bytes / 1024 / 1024).toFixed(1)} MiB`;
+/** A warning string when the mesh is over the advisory ceiling, else null. */
+function meshSizeWarning(size, kind, allowOversize) {
+    const max = ADVISORY_MAX_MESH_BYTES[kind];
+    if (size <= max)
+        return null;
+    return (`mesh is ${mib(size)}; the ${kind} limit ships at ${mib(max)} — the server has the final say` +
+        (allowOversize
+            ? ' (--allow-oversize requested, so the relaxed ceiling applies).'
+            : '. If this asset is deliberately heavy, re-run with --allow-oversize.'));
+}
+const HOST_KINDS = ['vehicle', 'character'];
+const HELIX_CHARACTER_SKELETON = 'helix-humanoid@1';
+const ADD_ON_OPS = ['tune', 'hide', 'mount', 'patch'];
+/**
+ * The slots whose add-ons ARE their ops — a clip-set pins one Vault animation version per pointer and ships no
+ * geometry, so it is the only add-on that publishes with no mesh.
+ * SYNC OBLIGATION: mirrored from the backend's `archetype: 'clip-set'` rows (helix-backend-api
+ * src/add-ons/character-slot-pack.ts + vehicle-slot-pack.ts); the slot registry there is authoritative.
+ */
+exports.CLIP_SET_SLOT_TYPES = [
+    'character.locomotion@1',
+    'character.voice@1',
+    'vehicle.exhaust_note@1',
+    'vehicle.blowoff@1',
+];
+/**
+ * The server's per-add-on op cap: 32 for every mesh archetype, 64 for a clip-set (a pack's ops are its content).
+ * SYNC OBLIGATION: helix-backend-api src/add-ons/vehicle-slot-pack.ts MAX_OPS_PER_ADD_ON / MAX_OPS_BY_ARCHETYPE.
+ */
+exports.MAX_ADD_ON_OPS = 32;
+exports.MAX_CLIP_SET_OPS = 64;
+function maxOpsForSlot(slotType) {
+    return typeof slotType === 'string' && exports.CLIP_SET_SLOT_TYPES.includes(slotType) ? exports.MAX_CLIP_SET_OPS : exports.MAX_ADD_ON_OPS;
+}
+/**
+ * Vehicle slots whose part may be PURE TUNING and so publish with no mesh (an ECU, gearbox, sway bars, brakes,
+ * coilovers, a tyre compound...): every vehicle `hardware` slot with tunable paths, plus the tyre slot. The add-on
+ * must carry at least one op and every op must be a `tune`.
+ * SYNC OBLIGATION: mirrored from helix-backend-api src/add-ons/vehicle-slot-pack.ts TUNE_ONLY_VEHICLE_SLOT_TYPES
+ * (the server is authoritative and refuses anything else).
+ */
+exports.TUNE_ONLY_VEHICLE_SLOT_TYPES = [
+    'vehicle.arb@1',
+    'vehicle.brakes@1',
+    'vehicle.driveline@1',
+    'vehicle.ecu@1',
+    'vehicle.engine@1',
+    'vehicle.exhaust@1',
+    'vehicle.induction@1',
+    'vehicle.intake@1',
+    'vehicle.steering@1',
+    'vehicle.suspension@1',
+    'vehicle.transmission@1',
+    'vehicle.tyre@1',
+];
+/** Is this a tune-only vehicle part: a mesh-optional slot and every op (at least one) a `tune`? */
+function isTuneOnlyVehiclePart(input) {
+    const slotType = input.fits?.slotType;
+    const ops = input.ops ?? [];
+    return input.kind === 'add_on' && typeof slotType === 'string' && exports.TUNE_ONLY_VEHICLE_SLOT_TYPES.includes(slotType)
+        && ops.length > 0 && ops.every((op) => op.v === 'tune');
+}
+/** Does this payload describe an add-on that legitimately arrives without a mesh? */
+function isMeshlessItem(input) {
+    const slotType = input.fits?.slotType;
+    return input.kind === 'add_on' && typeof slotType === 'string'
+        && (exports.CLIP_SET_SLOT_TYPES.includes(slotType) || isTuneOnlyVehiclePart(input));
+}
+function isObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** Parse either inline JSON or a JSON file path for a CLI metadata flag. */
+function parseJsonOrFile(value, flag) {
+    const trimmed = value.trim();
+    let source = trimmed;
+    let description = 'inline JSON';
+    if (!trimmed.startsWith('{') && !trimmed.startsWith('[')) {
+        const path = (0, node_path_1.resolve)(value);
+        if (!(0, node_fs_1.existsSync)(path)) {
+            throw new Error(`${flag} must be inline JSON or an existing JSON file (not found: ${path})`);
+        }
+        source = (0, node_fs_1.readFileSync)(path, 'utf8');
+        description = path;
+    }
+    try {
+        return JSON.parse(source);
+    }
+    catch (error) {
+        throw new Error(`${flag} is not valid JSON (${description}): ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+function parseJsonObjectOrFile(value, flag) {
+    const parsed = parseJsonOrFile(value, flag);
+    if (!isObject(parsed))
+        throw new Error(`${flag} must contain a JSON object`);
+    return parsed;
+}
+function parseJsonArrayOrFile(value, flag) {
+    const parsed = parseJsonOrFile(value, flag);
+    if (!Array.isArray(parsed) || parsed.some((entry) => !isObject(entry))) {
+        throw new Error(`${flag} must contain a JSON array of objects`);
+    }
+    return parsed;
+}
+function stringArray(value, pointer) {
+    if (!Array.isArray(value) || value.some((entry) => typeof entry !== 'string')) {
+        throw new Error(`${pointer} must be an array of strings`);
+    }
+    return value;
+}
+function assertFits(fits) {
+    if (typeof fits.slotType !== 'string' || fits.slotType.trim() === '') {
+        throw new Error('--fits.slotType is required and must be a non-empty string');
+    }
+    if (fits.slotType.length > 96)
+        throw new Error('--fits.slotType exceeds 96 characters');
+    if (!isObject(fits.requires))
+        throw new Error('--fits.requires is required and must be an object');
+    const requires = fits.requires;
+    for (const key of ['sockets', 'paths', 'pointers', 'nodes']) {
+        stringArray(requires[key], `--fits.requires.${key}`);
+    }
+    if (!(requires.skeleton === null || typeof requires.skeleton === 'string')) {
+        throw new Error('--fits.requires.skeleton must be a string or null');
+    }
+    if (fits.only !== undefined) {
+        if (!isObject(fits.only))
+            throw new Error('--fits.only must be an object');
+        for (const key of ['items', 'tags', 'creators']) {
+            if (fits.only[key] !== undefined)
+                stringArray(fits.only[key], `--fits.only.${key}`);
+        }
+        for (const [index, tag] of (fits.only.tags ?? []).entries()) {
+            if (tag.includes('*'))
+                throw new Error(`--fits.only.tags[${index}] may not contain a wildcard`);
+        }
+        for (const [index, creator] of (fits.only.creators ?? []).entries()) {
+            const id = creator.startsWith('grp:') ? creator.slice(4) : creator;
+            if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(id)) {
+                throw new Error(`--fits.only.creators[${index}] must be a user UUID or grp:<group UUID>`);
+            }
+        }
+    }
+}
+function assertOps(ops, fits) {
+    // The server caps a mesh archetype at 32 and a clip-set at 64 (a pack's ops are its content, and the
+    // locomotion vocabulary alone is 38 names). Refuse locally at the cap the server will apply to THIS slot.
+    const maxOps = maxOpsForSlot(fits.slotType);
+    if (ops.length > maxOps) {
+        throw new Error(`--ops may contain at most ${maxOps} operations for ${String(fits.slotType)} (got ${ops.length})`);
+    }
+    const requires = fits.requires;
+    for (const [index, op] of ops.entries()) {
+        const pointer = `--ops[${index}]`;
+        if (!ADD_ON_OPS.includes(op.v)) {
+            throw new Error(`${pointer}.v must be tune, hide, mount, or patch`);
+        }
+        if (op.v === 'tune') {
+            if (typeof op.path !== 'string' || !requires.paths.includes(op.path)) {
+                throw new Error(`${pointer}.path must name a path declared in --fits.requires.paths`);
+            }
+            if (!['set', 'mul', 'add'].includes(String(op.op))) {
+                throw new Error(`${pointer}.op must be set, mul, or add`);
+            }
+            if (op.value === undefined)
+                throw new Error(`${pointer}.value is required`);
+        }
+        else if (op.v === 'hide') {
+            const nodes = stringArray(op.nodes, `${pointer}.nodes`);
+            const required = requires.nodes;
+            if (nodes.some((node) => !required.some((glob) => globCovers(glob, node)))) {
+                throw new Error(`${pointer}.nodes must be declared in --fits.requires.nodes`);
+            }
+        }
+        else if (op.v === 'mount') {
+            if (!isObject(op.row) || typeof op.row.type !== 'string' || typeof op.row.id !== 'string') {
+                throw new Error(`${pointer}.row must contain string type and id fields`);
+            }
+        }
+        else {
+            if (typeof op.at !== 'string')
+                throw new Error(`${pointer}.at must be a string`);
+            const pointers = requires.pointers;
+            if (!pointers.some((glob) => globCovers(glob, op.at))) {
+                throw new Error(`${pointer}.at must be declared in --fits.requires.pointers`);
+            }
+            if (op.op !== 'set' && op.op !== 'remove') {
+                throw new Error(`${pointer}.op must be set or remove`);
+            }
+            if (op.op === 'set' && op.value === undefined) {
+                throw new Error(`${pointer}.value is required for a set patch`);
+            }
+        }
+    }
+}
+/**
+ * Validate the Universal Item add-on contract used by both item publication
+ * and Bridge-generated character add-ons. Keeping this as the single runtime
+ * validator prevents Bridge profiles from accepting operations that the item
+ * publisher would later reject.
+ */
+function validateAddOnContract(fits, ops = []) {
+    if (!isObject(fits))
+        throw new Error('--fits must be an object');
+    if (!Array.isArray(ops) || ops.some((entry) => !isObject(entry))) {
+        throw new Error('--ops must be an array of objects');
+    }
+    const validatedOps = ops;
+    assertFits(fits);
+    assertOps(validatedOps, fits);
+    return { fits, ops: validatedOps };
+}
+function globCovers(glob, value) {
+    const escaped = glob.replace(/[.+?^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*');
+    return new RegExp(`^${escaped}$`).test(value);
+}
+function assertHostSurface(surface) {
+    let measured = 0;
+    for (const key of ['sockets', 'nodes', 'materialSlots', 'paths']) {
+        const values = stringArray(surface[key] ?? [], `--host-surface.${key}`);
+        if (key === 'sockets' || key === 'nodes' || key === 'paths')
+            measured += values.length;
+    }
+    if (!(surface.skeleton === undefined || surface.skeleton === null || typeof surface.skeleton === 'string')) {
+        throw new Error('--host-surface.skeleton must be a string or null');
+    }
+    if (measured === 0) {
+        throw new Error('--host-surface must measure at least one socket, node, or path');
+    }
+}
+function assertAddOnAndHostFields(input) {
+    const hasOps = input.ops !== undefined;
+    if (input.kind === 'add_on') {
+        if (!input.fits)
+            throw new Error('An add_on must declare compatibility with --fits');
+        if (input.hostKind !== undefined || input.hostSurface !== undefined || input.includeStandardSlots !== undefined) {
+            throw new Error('An add_on cannot declare --host-kind, --host-surface or --include-standard-slots');
+        }
+        validateAddOnContract(input.fits, input.ops ?? []);
+        return;
+    }
+    if (input.fits !== undefined || hasOps) {
+        throw new Error(`Only an add_on may declare --fits or --ops (kind is "${input.kind}")`);
+    }
+    if (input.hostKind === undefined) {
+        if (input.hostSurface !== undefined || input.slots !== undefined || input.includeStandardSlots !== undefined) {
+            throw new Error('--host-surface, --slots and --include-standard-slots require --host-kind');
+        }
+        return;
+    }
+    if (!HOST_KINDS.includes(input.hostKind)) {
+        throw new Error(`--host-kind must be one of ${HOST_KINDS.join(' | ')}`);
+    }
+    if (!input.hostSurface)
+        throw new Error('--host-kind requires --host-surface');
+    assertHostSurface(input.hostSurface);
+    if (input.hostKind === 'character') {
+        if (input.kind !== 'avatar') {
+            throw new Error('--host-kind character requires --kind avatar');
+        }
+        if (input.hostSurface.skeleton !== HELIX_CHARACTER_SKELETON) {
+            throw new Error(`--host-kind character requires --host-surface.skeleton=${HELIX_CHARACTER_SKELETON}`);
+        }
+    }
+}
+function assertVehiclePackage(input) {
+    if (input.kind !== 'vehicle') {
+        if (input.vehiclePackage !== undefined) {
+            throw new Error(`Only a vehicle may declare --vehicle-package (kind is "${input.kind}")`);
+        }
+        return;
+    }
+    const pkg = input.vehiclePackage;
+    if (!pkg)
+        throw new Error('A vehicle must declare an authored --vehicle-package');
+    if (pkg.packageVersion !== 1 && pkg.packageVersion !== 2) {
+        throw new Error('--vehicle-package.packageVersion must be 1 or 2');
+    }
+    if (pkg.packageVersion === 2 && pkg.schemaVersion !== 'helix.vehicle-package/2') {
+        throw new Error('--vehicle-package.schemaVersion must be helix.vehicle-package/2 for packageVersion 2');
+    }
+    if (typeof pkg.id !== 'string' || pkg.id.trim() === '') {
+        throw new Error('--vehicle-package.id must be a non-empty string');
+    }
+    if (!isObject(pkg.mesh))
+        throw new Error('--vehicle-package.mesh must be an object');
+    if (pkg.packageVersion === 1 && pkg.mesh.source !== 'universal-item') {
+        throw new Error('--vehicle-package.mesh.source must be "universal-item"');
+    }
+    if (pkg.packageVersion === 1 && pkg.mesh.ref !== '$self') {
+        throw new Error('--vehicle-package.mesh.ref must be "$self" so the server can pin the published item');
+    }
+}
+function vehiclePackageForPublish(value) {
+    if (!value)
+        return undefined;
+    if (value.packageVersion !== 2)
+        return value;
+    const mesh = value.mesh;
+    return {
+        ...structuredClone(value),
+        mesh: { ...structuredClone(mesh), source: 'universal-item', ref: '$self' },
+    };
+}
+/** Split a `--tags a,b,c` value: trimmed, empties dropped, order-preserving dedupe. */
+function parseTags(value) {
+    const seen = new Set();
+    const out = [];
+    for (const raw of value.split(',')) {
+        const tag = raw.trim();
+        if (!tag || seen.has(tag.toLowerCase()))
+            continue;
+        seen.add(tag.toLowerCase());
+        out.push(tag);
+    }
+    return out;
+}
+/**
+ * Build the JSON object sent as the multipart `payload` field, applying every
+ * local rule first. Keys the caller did not set are OMITTED, never sent as
+ * null — the backend defaults `category`/`usage` from `kind`, and sending a
+ * guess would override a default the server owns.
+ */
+function buildItemPayload(input) {
+    if (!isUploadableItemKind(input.kind)) {
+        throw new Error(`unsupported --kind "${input.kind}" — uploads accept ${describeUploadableItemKinds()}`);
+    }
+    if (input.category === 'device' && input.kind !== 'home_item') {
+        throw new Error('--category device requires --kind prop (home_item)');
+    }
+    assertCcSlot(input.kind, input.slot);
+    assertCcGenders(input.kind, input.genders);
+    assertAddOnAndHostFields(input);
+    assertVehiclePackage(input);
+    const title = input.title?.trim() ?? '';
+    if (!title)
+        throw new Error('--title is required');
+    if (title.length > 100)
+        throw new Error(`--title is ${title.length} characters; the limit is 100`);
+    const slug = input.slug?.trim();
+    if (slug !== undefined) {
+        if (!slug)
+            throw new Error('--slug cannot be empty (omit it to have one derived from the title)');
+        if (slug.length > 80)
+            throw new Error(`--slug is ${slug.length} characters; the limit is 80`);
+        if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(slug)) {
+            throw new Error(`--slug "${slug}" must be lowercase letters, digits and single hyphens`);
+        }
+    }
+    const edition = (0, distribution_1.editionFields)(input.collectibleSupply);
+    const initialDistribution = input.initialDistribution
+        ? (0, distribution_1.buildItemDistribution)(input.initialDistribution)
+        : undefined;
+    // ── THE ADD-ON VISIBILITY GATE ──────────────────────────────────────────────
+    //
+    // A published add-on with no ACTIVE MARKETPLACE distribution is live, fits its
+    // base, and is still unfindable: the customizer's compatibility shelf keeps an
+    // unowned tile only when the row carries a `distributionId` (helixgame.com
+    // `components/addons/equip-surface.tsx`, `shopRowAcquirable`), and that id is
+    // `deriveMarketplaceDistributions(item)[0]?.id` — active, in-window,
+    // `channel = 'marketplace'` rows only. A WORLD-channel route does NOT satisfy
+    // it, so a world-only add-on is just as invisible in the shelf as one with no
+    // route at all. Confirmed live 2026-09-29: 16 published character add-ons with
+    // no marketplace route rendered as "90 compatible" while eight of them were
+    // silently absent from the rail.
+    //
+    // So an add-on must EITHER carry a marketplace route OR be explicitly declared
+    // deliberately unlisted (`--no-marketplace`). Refusing here — rather than
+    // publishing and warning — is the point: the broken state is invisible to its
+    // own creator, so a warning on an otherwise-successful publish is exactly the
+    // signal that gets missed. This runs in `planItemPublish`, so `--dry-run` and
+    // `--quote` refuse too, before any byte is uploaded and before a fee moves.
+    if (input.noMarketplace === true && initialDistribution?.channel === 'marketplace') {
+        throw new Error('--no-marketplace says this add-on is deliberately unlisted, so it cannot also carry a Marketplace route');
+    }
+    if (input.kind === 'add_on' &&
+        input.noMarketplace !== true &&
+        initialDistribution?.channel !== 'marketplace') {
+        throw new Error('an add-on with no Marketplace route publishes as a live but UNFINDABLE item — it fits its base, '
+            + "yet no player can see or acquire it in the customizer's compatibility list.\n"
+            + '  Give it one:  --distribution-price-lix 0   (free Claim)  or  --distribution-price-lix <n>   (sale)\n'
+            + '  Or, if it is deliberately unlisted (world-only, or not for sale):  --no-marketplace');
+    }
+    const tags = input.tags ?? [];
+    if (tags.length > 24)
+        throw new Error(`--tags carries ${tags.length} entries; the limit is 24`);
+    for (const tag of tags) {
+        if (tag.length > 40)
+            throw new Error(`tag "${tag}" is ${tag.length} characters; the limit is 40`);
+    }
+    const description = input.description?.trim();
+    // Canonical order, so `--gender female,male` and `--gender male,female` send
+    // byte-identical payloads.
+    const genders = parseGenders((input.genders ?? []).join(','));
+    return {
+        kind: input.kind,
+        ...(input.category ? { category: input.category } : {}),
+        title,
+        ...(slug !== undefined ? { slug } : {}),
+        ...(description ? { description } : {}),
+        ...(input.slot ? { slot: input.slot } : {}),
+        // The wire field is `genders`. NOT `ccGenders` — see the type above.
+        ...(genders.length ? { genders } : {}),
+        ...(tags.length ? { tags } : {}),
+        ...edition,
+        ...(initialDistribution ? { initialDistribution } : {}),
+        ...(input.allowOversize ? { allowOversize: true } : {}),
+        ...(input.fits ? { fits: input.fits } : {}),
+        ...(input.ops ? { ops: input.ops } : {}),
+        ...(input.hostKind ? { hostKind: input.hostKind } : {}),
+        ...(input.hostSurface ? { hostSurface: input.hostSurface } : {}),
+        ...(input.slots ? { slots: structuredClone(input.slots) } : {}),
+        ...(input.includeStandardSlots !== undefined
+            ? { includeStandardSlots: input.includeStandardSlots }
+            : {}),
+        ...(input.vehiclePackage
+            ? { vehiclePackage: vehiclePackageForPublish(input.vehiclePackage) }
+            : {}),
+    };
+}
+//# sourceMappingURL=item.js.map