@helix3/helix-cli 0.1.18-helix3.342 → 0.1.18-helix3.344

package/dist/character/restFrameGuard.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Refuse a `helix-humanoid@1` character GLB whose bones are not in the canonical rest FRAMES.
+ *
+ * ── THE DEFECT (live, found 2026-10-02 by the whole-catalogue visual-QA sweep) ───────────────────────
+ * Cyberpunk Female Base 1.0.4–1.0.7 shipped with every bone frame turned 180 degrees about the vertical axis.
+ * The source faced -Z, the importer (`fitSkeletonToWarrior`) embedded the canonical skeleton at the source's joint
+ * positions (so left-side bones sat on the -X side of the root frame) and the author turned the whole thing round
+ * with a `cyberpunk_forward_frame` wrapper node (q 0,1,0,0) above skeleton AND mesh. A wrapper like that keeps
+ * every WORLD POSITION right, so it renders correctly at rest, in every thumbnail and in every T-pose proof — and
+ * leaves every bone FRAME 180 degrees off canonical. The clips are absolute canonical local rotations
+ * (`retargetLocomotion.ts`: "Canonical rotations are absolute local poses"), so idle folded both hands behind the
+ * back and the walk/run swung the arms and legs the wrong way round. Every skinned add-on bound to that base inherits
+ * the rig, so none of them could be fitted or posed correctly either.
+ *
+ * ── WHY EVERY EXISTING GATE PASSED IT ──────────────────────────────────────────────────────────────
+ * Same story as `normalMapGuard.ts`: skeleton checks compare joint NAMES, ORDER and rest POSITIONS. None compared
+ * a rest ORIENTATION to anything.
+ *
+ * ── THE TEST ───────────────────────────────────────────────────────────────────────────────────────
+ * Every conformed `helix-humanoid@1` body measured on 2026-10-02 (17 live characters, Base Male/Female, Sims 4,
+ * Kemonomimi, Unitree G1, Brass Keeper...) has its trunk, neck, head, leg and foot frames within 35 degrees of the
+ * canonical rest world frame, and its arm chain (aimed at the source's own arm pose) within 65. The flipped
+ * Cyberpunk base is at 171-180 on every one of them. Anything past `REST_FRAME_MAX_DEVIATION_DEG` is a turned or
+ * rolled skeleton, never a pose difference. Only a rig that actually carries the canonical joint names is judged;
+ * a rig with none of them is somebody else's skeleton and is left alone.
+ *
+ * Escape hatch: `HELIX_ALLOW_NONCANONICAL_REST_FRAMES=1`.
+ */
+import type { Document } from '@gltf-transform/core';
+export declare const REST_FRAME_MAX_DEVIATION_DEG = 100;
+/** The bones every humanoid body must have in the canonical orientation: trunk, head, legs, feet and the arm chain. */
+export declare const REST_FRAME_CHECKED_JOINTS: readonly string[];
+export interface RestFrameFinding {
+    joint: string;
+    degrees: number;
+}
+export interface RestFrameReport {
+    /** Joints actually compared (those present in both the GLB and the canonical skeleton). */
+    checked: number;
+    findings: RestFrameFinding[];
+}
+/** Compare the first skin's joint WORLD frames (wrapper nodes included: they are part of what the engine draws) to canonical. */
+export declare function inspectRestFrames(document: Document): RestFrameReport;
+export declare function describeRestFrameFindings(findings: readonly RestFrameFinding[]): string;
+/** Throws with an itemized report when the rig is a canonical humanoid that is turned or rolled away from the canonical frames. */
+export declare function assertRestFramesAreCanonical(document: Document, name?: string): RestFrameReport;
+export declare function assertGlbRestFramesAreCanonical(glb: Uint8Array, name?: string): Promise<RestFrameReport>;
+/** Shared by publish and publish --dry-run, so the gate before the fee is the gate at it. Character BASES only: an add-on carries a part skeleton judged by its host. */
+export declare function assertPublishRestFrames(opts: {
+    kind: string;
+    mesh?: string;
+}, meshBytes: Uint8Array | null | undefined): Promise<void>;

package/dist/character/restFrameGuard.js

@@ -0,0 +1,90 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REST_FRAME_CHECKED_JOINTS = exports.REST_FRAME_MAX_DEVIATION_DEG = void 0;
+exports.inspectRestFrames = inspectRestFrames;
+exports.describeRestFrameFindings = describeRestFrameFindings;
+exports.assertRestFramesAreCanonical = assertRestFramesAreCanonical;
+exports.assertGlbRestFramesAreCanonical = assertGlbRestFramesAreCanonical;
+exports.assertPublishRestFrames = assertPublishRestFrames;
+const core_1 = require("@gltf-transform/core");
+const extensions_1 = require("@gltf-transform/extensions");
+const canonicalSkeleton_1 = require("./canonicalSkeleton");
+exports.REST_FRAME_MAX_DEVIATION_DEG = 100;
+/** The bones every humanoid body must have in the canonical orientation: trunk, head, legs, feet and the arm chain. */
+exports.REST_FRAME_CHECKED_JOINTS = [
+    'pelvis', 'spine_01', 'spine_05', 'neck_01', 'head',
+    'clavicle_l', 'clavicle_r',
+    'upperarm_l', 'upperarm_r', 'lowerarm_l', 'lowerarm_r',
+    'thigh_l', 'thigh_r', 'calf_l', 'calf_r', 'foot_l', 'foot_r',
+];
+/** Rotation angle, in degrees, between two column-major 4x4 world matrices' orthonormalised 3x3 parts. */
+function angleBetween(a, b) {
+    const col = (m, c) => {
+        const v = [m[4 * c], m[4 * c + 1], m[4 * c + 2]];
+        const l = Math.hypot(...v) || 1;
+        return [v[0] / l, v[1] / l, v[2] / l];
+    };
+    // trace(Ra^T * Rb) = sum over columns of dot(a_c, b_c) (scale-free: each column is normalised first)
+    let trace = 0;
+    for (let c = 0; c < 3; c += 1) {
+        const x = col(a, c);
+        const y = col(b, c);
+        trace += x[0] * y[0] + x[1] * y[1] + x[2] * y[2];
+    }
+    return (Math.acos(Math.max(-1, Math.min(1, (trace - 1) / 2))) * 180) / Math.PI;
+}
+/** Compare the first skin's joint WORLD frames (wrapper nodes included: they are part of what the engine draws) to canonical. */
+function inspectRestFrames(document) {
+    const skin = document.getRoot().listSkins()[0];
+    if (!skin)
+        return { checked: 0, findings: [] };
+    const canonical = (0, canonicalSkeleton_1.vendoredCanonicalSkeleton)().worldByName;
+    const findings = [];
+    let checked = 0;
+    const byName = new Map(skin.listJoints().map((joint) => [joint.getName(), joint]));
+    for (const name of exports.REST_FRAME_CHECKED_JOINTS) {
+        const joint = byName.get(name);
+        const reference = canonical.get(name);
+        if (!joint || !reference)
+            continue;
+        checked += 1;
+        const degrees = angleBetween(joint.getWorldMatrix(), reference);
+        if (degrees > exports.REST_FRAME_MAX_DEVIATION_DEG)
+            findings.push({ joint: name, degrees: Math.round(degrees) });
+    }
+    return { checked, findings };
+}
+function describeRestFrameFindings(findings) {
+    return findings.map((f) => `  - ${f.joint}: ${f.degrees} deg from the canonical rest frame`).join('\n');
+}
+/** Throws with an itemized report when the rig is a canonical humanoid that is turned or rolled away from the canonical frames. */
+function assertRestFramesAreCanonical(document, name = 'this GLB') {
+    const report = inspectRestFrames(document);
+    // fewer than five canonical joints present: not a conformed helix-humanoid rig, not ours to judge
+    if (report.checked < 5 || report.findings.length === 0 || process.env.HELIX_ALLOW_NONCANONICAL_REST_FRAMES === '1')
+        return report;
+    throw new Error(`Refusing ${name}: ${report.findings.length} of ${report.checked} checked bone frames are more than ${exports.REST_FRAME_MAX_DEVIATION_DEG} degrees from the canonical ` +
+        `helix-humanoid@1 rest frames, so every clip will drive this body turned or mirrored (hands folded behind the back in idle, arms and legs swinging the wrong way).\n` +
+        `${describeRestFrameFindings(report.findings)}\n` +
+        `This is a turned or rolled skeleton, not a pose: a wrapper node (e.g. a 180-degree forward frame) above the skeleton keeps every position right and every frame wrong. ` +
+        `Re-conform the source facing +Z, or bake the wrapper into the mesh and give each bone the canonical frame at the same position. ` +
+        `To ship anyway set HELIX_ALLOW_NONCANONICAL_REST_FRAMES=1.`);
+}
+async function assertGlbRestFramesAreCanonical(glb, name) {
+    let document;
+    try {
+        document = await new core_1.NodeIO().registerExtensions(extensions_1.ALL_EXTENSIONS).readBinary(glb);
+    }
+    catch {
+        return { checked: 0, findings: [] };
+    }
+    return assertRestFramesAreCanonical(document, name);
+}
+const REST_FRAME_GUARDED_KINDS = new Set(['avatar']);
+/** Shared by publish and publish --dry-run, so the gate before the fee is the gate at it. Character BASES only: an add-on carries a part skeleton judged by its host. */
+async function assertPublishRestFrames(opts, meshBytes) {
+    if (!meshBytes || !REST_FRAME_GUARDED_KINDS.has(opts.kind))
+        return;
+    await assertGlbRestFramesAreCanonical(meshBytes, opts.mesh ?? 'the mesh');
+}
+//# sourceMappingURL=restFrameGuard.js.map

package/dist/character/restFrameGuard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"restFrameGuard.js","sourceRoot":"","sources":["../../src/character/restFrameGuard.ts"],"names":[],"mappings":";;;AAwEA,8CAgBC;AAED,8DAEC;AAGD,oEAYC;AAED,0EAQC;AAKD,0DAGC;AAhGD,+CAA8C;AAC9C,2DAA4D;AAC5D,2DAAgE;AAEnD,QAAA,4BAA4B,GAAG,GAAG,CAAC;AAEhD,uHAAuH;AAC1G,QAAA,yBAAyB,GAAsB;IAC1D,QAAQ,EAAE,UAAU,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM;IACnD,YAAY,EAAE,YAAY;IAC1B,YAAY,EAAE,YAAY,EAAE,YAAY,EAAE,YAAY;IACtD,SAAS,EAAE,SAAS,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ;CAC7D,CAAC;AAaF,0GAA0G;AAC1G,SAAS,YAAY,CAAC,CAAoB,EAAE,CAAoB;IAC9D,MAAM,GAAG,GAAG,CAAC,CAAoB,EAAE,CAAS,EAA4B,EAAE;QACxE,MAAM,CAAC,GAA6B,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAE,CAAC,CAAC;QAC9E,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC;QAChC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IACxC,CAAC,CAAC;IACF,qGAAqG;IACrG,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;QAC9B,MAAM,CAAC,GAAG,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QACpB,MAAM,CAAC,GAAG,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QACpB,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IACnD,CAAC;IACD,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,KAAK,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,GAAG,IAAI,CAAC,EAAE,CAAC;AACjF,CAAC;AAED,iIAAiI;AACjI,SAAgB,iBAAiB,CAAC,QAAkB;IAClD,MAAM,IAAI,GAAG,QAAQ,CAAC,OAAO,EAAE,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,CAAC;IAC/C,IAAI,CAAC,IAAI;QAAE,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC;IAC/C,MAAM,SAAS,GAAG,IAAA,6CAAyB,GAAE,CAAC,WAAW,CAAC;IAC1D,MAAM,QAAQ,GAAuB,EAAE,CAAC;IACxC,IAAI,OAAO,GAAG,CAAC,CAAC;IAChB,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,UAAU,EAAE,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,EAAE,EAAE,KAAK,CAAU,CAAC,CAAC,CAAC;IAC5F,KAAK,MAAM,IAAI,IAAI,iCAAyB,EAAE,CAAC;QAC7C,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAC/B,MAAM,SAAS,GAAG,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACtC,IAAI,CAAC,KAAK,IAAI,CAAC,SAAS;YAAE,SAAS;QACnC,OAAO,IAAI,CAAC,CAAC;QACb,MAAM,OAAO,GAAG,YAAY,CAAC,KAAK,CAAC,cAAc,EAAc,EAAE,SAAS,CAAC,CAAC;QAC5E,IAAI,OAAO,GAAG,oCAA4B;YAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;IAC3G,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC;AAC/B,CAAC;AAED,SAAgB,yBAAyB,CAAC,QAAqC;IAC7E,OAAO,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,OAAO,oCAAoC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1G,CAAC;AAED,mIAAmI;AACnI,SAAgB,4BAA4B,CAAC,QAAkB,EAAE,IAAI,GAAG,UAAU;IAChF,MAAM,MAAM,GAAG,iBAAiB,CAAC,QAAQ,CAAC,CAAC;IAC3C,kGAAkG;IAClG,IAAI,MAAM,CAAC,OAAO,GAAG,CAAC,IAAI,MAAM,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC,IAAI,OAAO,CAAC,GAAG,CAAC,oCAAoC,KAAK,GAAG;QAAE,OAAO,MAAM,CAAC;IAClI,MAAM,IAAI,KAAK,CACb,YAAY,IAAI,KAAK,MAAM,CAAC,QAAQ,CAAC,MAAM,OAAO,MAAM,CAAC,OAAO,sCAAsC,oCAA4B,8BAA8B;QAC9J,qKAAqK;QACrK,GAAG,yBAAyB,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI;QACjD,yKAAyK;QACzK,kIAAkI;QAClI,4DAA4D,CAC/D,CAAC;AACJ,CAAC;AAEM,KAAK,UAAU,+BAA+B,CAAC,GAAe,EAAE,IAAa;IAClF,IAAI,QAAkB,CAAC;IACvB,IAAI,CAAC;QACH,QAAQ,GAAG,MAAM,IAAI,aAAM,EAAE,CAAC,kBAAkB,CAAC,2BAAc,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;IACnF,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC;IACtC,CAAC;IACD,OAAO,4BAA4B,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;AACtD,CAAC;AAED,MAAM,wBAAwB,GAAG,IAAI,GAAG,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC;AAErD,yKAAyK;AAClK,KAAK,UAAU,uBAAuB,CAAC,IAAqC,EAAE,SAAwC;IAC3H,IAAI,CAAC,SAAS,IAAI,CAAC,wBAAwB,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC;QAAE,OAAO;IACnE,MAAM,+BAA+B,CAAC,SAAS,EAAE,IAAI,CAAC,IAAI,IAAI,UAAU,CAAC,CAAC;AAC5E,CAAC"}

package/dist/index.js

@@ -38,6 +38,7 @@ const baseColorGuard_1 = require("./character/baseColorGuard");
 const normalMapGuard_1 = require("./character/normalMapGuard");
 const itemSetVersion_1 = require("./itemSetVersion");
 const moveUx_1 = require("./visualQa/moveUx");
+const restFrameGuard_1 = require("./character/restFrameGuard");
 const commander_1 = require("commander");
 const commands_1 = require("./sceneHlod/commands");
 const placementRequest_1 = require("./placementRequest");
@@ -86,7 +87,14 @@ program
     .description('HELIX creator CLI — scaffold, validate, and publish Instant Worlds')
     .version((0, lib_1.cliVersion)());
 function fail(message) {
-    console.error(message);
+    // Synchronous: stderr is an ASYNC pipe on macOS, so console.error + process.exit cut a long refusal at ~512 bytes
+    // whenever the output was piped — exactly how an agent or CI reads it — losing the next command it names.
+    try {
+        (0, node_fs_1.writeSync)(2, `${message}\n`);
+    }
+    catch {
+        console.error(message);
+    }
     process.exit(1);
 }
 function requireAuth() {
@@ -1631,6 +1639,7 @@ item
             const plan = (0, lib_1.planItemPublish)(publishOptions);
             await (0, baseColorGuard_1.assertPublishBaseColor)(publishOptions, plan.meshBytes);
             await (0, normalMapGuard_1.assertPublishNormalMaps)(publishOptions, plan.meshBytes);
+            await (0, restFrameGuard_1.assertPublishRestFrames)(publishOptions, plan.meshBytes);
             if (opts.json) {
                 console.log(JSON.stringify({
                     dryRun: true,
@@ -1811,14 +1820,15 @@ item
                 if (opts.json)
                     console.log(JSON.stringify(st, null, 2));
                 else {
-                    console.log(`hosted job: ${hosted.describeJob(job)}`);
+                    // Current version first, with ITS hosted job; pending versions (each with their own job) follow.
+                    console.log(`current version: ${st.currentVersion ? (st.currentVersion.passed ? 'PASSED' : 'no passing run') : 'not pinned to a package version'}`);
+                    console.log(`  hosted job for the current version: ${hosted.describeJob(job)}`);
                     if (job?.contactSheetUrl)
-                        console.log(`  contact sheet: ${job.contactSheetUrl}`);
+                        console.log(`    contact sheet: ${job.contactSheetUrl}`);
                     for (const r of job?.reasons ?? [])
-                        console.log(`  - ${r}`);
+                        console.log(`    - ${r}`);
                     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'}`);
+                        console.log(`    error: ${job.error}`);
                     for (const line of (0, moveUx_1.describePendingVersions)(id, st.pendingVersions))
                         console.log(line);
                 }