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

package/dist/pack/locomotionReference.d.ts

@@ -0,0 +1,40 @@
+/**
+ * How far a pack clip's stride may sit either side of the platform clip it replaces. The engine's
+ * `PACK_STRIDE_BAND` CLAMPS an out-of-band stride so a bought pack keeps playing; the publish gate REFUSES it,
+ * so a pack that only looks right because the runtime corrected it never ships. This lane takes the gate's posture.
+ */
+export declare const PACK_STRIDE_BAND: {
+    readonly minRatio: 0.5;
+    readonly maxRatio: 1.5;
+};
+/** `null` is the CLASSIFICATION, not a missing number: the clip does not travel, so a stride on it is a mistake. */
+export declare const LOCOMOTION_CLIP_STRIDE: Readonly<Record<string, number | null>>;
+/** The three gaits the ladder walks. Ring members are measured against their own base gait instead. */
+export declare const GAIT_LADDER: readonly ["walk", "run", "sprint"];
+/** The slot's `patch` grant — the GAIT vocabulary only, which is what keeps death/getup/hit/sit/lie out of a pack. */
+export declare const LOCOMOTION_CLIP_POINTERS: readonly string[];
+/** The namespace every pack clip's meta `name` carries; the pointer takes the bare name after it. */
+export declare const LOCOMOTION_NAME_PREFIX = "locomotion.";
+/** The clip-set slot a locomotion pack occupies, and the rig its clips must target. */
+export declare const LOCOMOTION_SLOT_TYPE = "character.locomotion@1";
+export declare const LOCOMOTION_SKELETON = "helix-humanoid@1";
+/** The three gaits that may carry a directional ring, and the fixed suffix → degrees grid the gate accepts. */
+export declare const RING_GAITS: readonly ["walk", "run", "crouchWalk"];
+export declare const RING_DIRECTION_DEG: Readonly<Record<string, number>>;
+export type StrideReference = {
+    /** The platform clip this name is measured against — itself, or its ring's base gait. */
+    referenceName: string;
+    strideSpeed: number | null;
+};
+/**
+ * What a pack clip of this name is measured against: its own platform clip when one exists, else the base gait
+ * of the directional ring it belongs to. `null` for a name outside the platform vocabulary entirely — nothing
+ * travels by default, so such a clip may not claim a stride.
+ */
+export declare function strideReferenceFor(name: string): StrideReference | null;
+/** Is this bare clip name inside the slot's gait-only grant? */
+export declare function isGrantedClipName(bareName: string): boolean;
+/** The ring suffix a name ends in (`walkFL` → `FL`), or null when it is a forward clip or not a ring member. */
+export declare function ringSuffixOf(bareName: string): string | null;
+/** Renders a speed without dragging float noise (0.7000000000000001) into a message — the gate's own helper. */
+export declare function speed(value: number): string;

package/dist/pack/locomotionReference.js

@@ -0,0 +1,132 @@
+"use strict";
+// THE PLATFORM LOCOMOTION SET — every clip name `character.locomotion@1` grants, with the stride the platform
+// clip travels at (m/s), the band a pack clip may sit in, and the gait-only pointer vocabulary of the slot.
+//
+// SYNC OBLIGATION — two upstreams, both authoritative for a different half:
+//   1. helix-web-engine-new/asset-packs/humanoid-character/anims/clip-meta.json is the SOURCE OF TRUTH for the
+//      numbers. Re-measure a platform clip there and this table must be re-copied.
+//   2. helix-backend-api src/add-ons/locomotion-clip-reference.ts (+ the `anim.locomotion` row in
+//      src/add-ons/character-slot-pack.ts) is the ENFORCING GATE. This file is the local fast path so a pack
+//      fails in a second instead of after 38 uploads; the server is always the last word.
+// This is knowingly the fourth copy of the table (engine runtime, engine pack data, backend, here). Fix the
+// engine first, then mirror outwards — a divergence here refuses a pack for matching the shipped engine.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RING_DIRECTION_DEG = exports.RING_GAITS = exports.LOCOMOTION_SKELETON = exports.LOCOMOTION_SLOT_TYPE = exports.LOCOMOTION_NAME_PREFIX = exports.LOCOMOTION_CLIP_POINTERS = exports.GAIT_LADDER = exports.LOCOMOTION_CLIP_STRIDE = exports.PACK_STRIDE_BAND = void 0;
+exports.strideReferenceFor = strideReferenceFor;
+exports.isGrantedClipName = isGrantedClipName;
+exports.ringSuffixOf = ringSuffixOf;
+exports.speed = speed;
+/**
+ * How far a pack clip's stride may sit either side of the platform clip it replaces. The engine's
+ * `PACK_STRIDE_BAND` CLAMPS an out-of-band stride so a bought pack keeps playing; the publish gate REFUSES it,
+ * so a pack that only looks right because the runtime corrected it never ships. This lane takes the gate's posture.
+ */
+exports.PACK_STRIDE_BAND = { minRatio: 0.5, maxRatio: 1.5 };
+/** `null` is the CLASSIFICATION, not a missing number: the clip does not travel, so a stride on it is a mistake. */
+exports.LOCOMOTION_CLIP_STRIDE = {
+    idle: null,
+    walk: 2.049,
+    walkB: 1.537,
+    walkBL: 1.537,
+    walkBR: 1.537,
+    walkFL: 2.049,
+    walkFR: 2.049,
+    walkL: 1.844,
+    walkR: 1.844,
+    run: 5.096,
+    runB: 3.059,
+    runBL: 3.059,
+    runBR: 3.059,
+    runFL: 5.096,
+    runFR: 5.096,
+    runL: 3.565,
+    runR: 3.566,
+    sprint: 7.111,
+    crouchIdle: null,
+    crouchWalk: 2.303,
+    crouchWalkB: 1.843,
+    crouchWalkBL: 1.859,
+    crouchWalkBR: 1.844,
+    crouchWalkFL: 2.304,
+    crouchWalkFR: 2.304,
+    crouchWalkL: 2.049,
+    crouchWalkR: 2.048,
+    jumpStart: null,
+    fall: null,
+    land: null,
+    turnL90: null,
+    turnL180: null,
+    turnR90: null,
+    turnR180: null,
+    crouchTurnL90: null,
+    crouchTurnL180: null,
+    crouchTurnR90: null,
+    crouchTurnR180: null,
+};
+/** The three gaits the ladder walks. Ring members are measured against their own base gait instead. */
+exports.GAIT_LADDER = ['walk', 'run', 'sprint'];
+/** Longest-first, so `crouchWalkFL` resolves to `crouchWalk` rather than to `walk`. */
+const RING_BASES = ['crouchWalk', 'crouchTurn', 'sprint', 'walk', 'run', 'turn'];
+/** The slot's `patch` grant — the GAIT vocabulary only, which is what keeps death/getup/hit/sit/lie out of a pack. */
+exports.LOCOMOTION_CLIP_POINTERS = [
+    '/clips/idle',
+    '/clips/walk*',
+    '/clips/run*',
+    '/clips/sprint*',
+    '/clips/crouchIdle',
+    '/clips/crouchWalk*',
+    '/clips/jumpStart',
+    '/clips/fall',
+    '/clips/land',
+    '/clips/turn*',
+    '/clips/crouchTurn*',
+];
+/** The namespace every pack clip's meta `name` carries; the pointer takes the bare name after it. */
+exports.LOCOMOTION_NAME_PREFIX = 'locomotion.';
+/** The clip-set slot a locomotion pack occupies, and the rig its clips must target. */
+exports.LOCOMOTION_SLOT_TYPE = 'character.locomotion@1';
+exports.LOCOMOTION_SKELETON = 'helix-humanoid@1';
+/** The three gaits that may carry a directional ring, and the fixed suffix → degrees grid the gate accepts. */
+exports.RING_GAITS = ['walk', 'run', 'crouchWalk'];
+exports.RING_DIRECTION_DEG = {
+    FL: 45,
+    FR: -45,
+    L: 90,
+    R: -90,
+    BL: 135,
+    BR: -135,
+    B: 180,
+};
+/**
+ * What a pack clip of this name is measured against: its own platform clip when one exists, else the base gait
+ * of the directional ring it belongs to. `null` for a name outside the platform vocabulary entirely — nothing
+ * travels by default, so such a clip may not claim a stride.
+ */
+function strideReferenceFor(name) {
+    if (Object.prototype.hasOwnProperty.call(exports.LOCOMOTION_CLIP_STRIDE, name)) {
+        return { referenceName: name, strideSpeed: exports.LOCOMOTION_CLIP_STRIDE[name] };
+    }
+    const base = RING_BASES.find((candidate) => name.startsWith(candidate));
+    return base ? { referenceName: base, strideSpeed: exports.LOCOMOTION_CLIP_STRIDE[base] } : null;
+}
+/** `*` is the only wildcard, matching the glob grammar the gate reads a slot's grant with. */
+function globCovers(glob, value) {
+    return new RegExp(`^${glob.replace(/[.+?^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*')}$`).test(value);
+}
+/** Is this bare clip name inside the slot's gait-only grant? */
+function isGrantedClipName(bareName) {
+    return exports.LOCOMOTION_CLIP_POINTERS.some((glob) => globCovers(glob, `/clips/${bareName}`));
+}
+/** The ring suffix a name ends in (`walkFL` → `FL`), or null when it is a forward clip or not a ring member. */
+function ringSuffixOf(bareName) {
+    const gait = exports.RING_GAITS.find((candidate) => bareName.startsWith(candidate) && bareName.length > candidate.length);
+    if (gait === undefined)
+        return null;
+    const suffix = bareName.slice(gait.length);
+    return exports.RING_DIRECTION_DEG[suffix] === undefined ? null : suffix;
+}
+/** Renders a speed without dragging float noise (0.7000000000000001) into a message — the gate's own helper. */
+function speed(value) {
+    return `${Math.round(value * 1000) / 1000} m/s`;
+}
+//# sourceMappingURL=locomotionReference.js.map

package/dist/pack/locomotionReference.js.map

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

package/dist/pack/scaffold.d.ts

@@ -0,0 +1,15 @@
+export type PackScaffoldInput = {
+    dir: string;
+    /** Replace files that already exist. Without it an existing clip-meta.json is left alone. */
+    overwrite?: boolean;
+};
+export type PackScaffoldResult = {
+    dir: string;
+    metaPath: string;
+    readmePath: string;
+    /** Pack-relative paths actually written — an existing file is skipped without --overwrite. */
+    created: string[];
+    skipped: string[];
+    nextSteps: string[];
+};
+export declare function scaffoldLocomotionPack(input: PackScaffoldInput): PackScaffoldResult;

package/dist/pack/scaffold.js

@@ -0,0 +1,144 @@
+"use strict";
+// `helix pack scaffold` — emit a starter locomotion pack in the engine's asset-pack shape: `anims/clip-meta.json`
+// with one example entry, plus a README carrying the authoring rules the publish gate enforces. No network.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.scaffoldLocomotionPack = scaffoldLocomotionPack;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const locomotionReference_1 = require("./locomotionReference");
+/** The single example entry: a styled forward walk, the smallest pack that is a product. */
+const EXAMPLE_CLIP = {
+    name: `${locomotionReference_1.LOCOMOTION_NAME_PREFIX}walk`,
+    loop: true,
+    duration: 4.0,
+    strideSpeed: locomotionReference_1.LOCOMOTION_CLIP_STRIDE.walk,
+    direction: 0,
+};
+const band = (name) => {
+    const reference = locomotionReference_1.LOCOMOTION_CLIP_STRIDE[name];
+    if (typeof reference !== 'number')
+        return '—';
+    return `${(reference * locomotionReference_1.PACK_STRIDE_BAND.minRatio).toFixed(2)} – ${(reference * locomotionReference_1.PACK_STRIDE_BAND.maxRatio).toFixed(2)}`;
+};
+function readmeText() {
+    const travelling = Object.entries(locomotionReference_1.LOCOMOTION_CLIP_STRIDE).filter(([, stride]) => typeof stride === 'number');
+    const strideRows = travelling
+        .map(([name, stride]) => `| \`${locomotionReference_1.LOCOMOTION_NAME_PREFIX}${name}\` | ${stride.toFixed(3)} | ${band(name)} |`)
+        .join('\n');
+    const ringRows = Object.entries(locomotionReference_1.RING_DIRECTION_DEG)
+        .map(([suffix, deg]) => `| \`${suffix}\` | ${deg > 0 ? `+${deg}` : deg} |`)
+        .join('\n');
+    return `# Locomotion pack
+
+A set of replacement animation clips for the humanoid character's movement, published as a character add-on in
+the \`${locomotionReference_1.LOCOMOTION_SLOT_TYPE}\` slot. It is DATA, not code: one GLB animation per clip plus one metadata entry.
+
+The governing rule of the slot: a pack may change how a walk *looks*; it may never change how far that walk
+*gets you*. Movement speed belongs to the world's config — \`strideSpeed\` is a MEASUREMENT of the authored
+motion, used for blending and anti-foot-slide.
+
+**Partial packs are valid products, down to a single clip.** Every name you do not supply falls back to the
+platform clip. There is no completeness roster.
+
+## Layout
+
+\`\`\`
+<pack>/
+  anims/
+    clip-meta.json            # this array
+    ${locomotionReference_1.LOCOMOTION_NAME_PREFIX}walk.glb       # one GLB per entry; file name = the entry's name + ".glb"
+    ${locomotionReference_1.LOCOMOTION_NAME_PREFIX}run.glb
+\`\`\`
+
+The GLB file name must equal the entry's \`name\` EXACTLY, including the \`${locomotionReference_1.LOCOMOTION_NAME_PREFIX}\` prefix.
+
+## \`clip-meta.json\` entries
+
+| Field | Type | Required | Meaning |
+|---|---|---|---|
+| \`name\` | string | yes | \`${locomotionReference_1.LOCOMOTION_NAME_PREFIX}<clip>\`, from the gait vocabulary below. |
+| \`loop\` | boolean | yes | \`true\` cycles (gaits, idles, fall); \`false\` plays once (jumpStart, land, turn steps). |
+| \`duration\` | number | yes | Clip length in seconds. **Must equal the GLB animation's actual length** — it is pinned into the published version's metadata, which is immutable, and the gate refuses a pin with no duration. |
+| \`strideSpeed\` | number \\| null | yes | Measured XZ ground speed of the SOURCE motion, m/s. \`null\` for a clip that does not travel. |
+| \`direction\` | number | ring clips only | Signed degrees off the gait's own forward clip; positive is the character's left. |
+| \`hadRootMotion\` | boolean | no | Pipeline provenance. Ignored by the runtime. |
+
+## GLB requirements
+
+- **One animation per file.** The loader takes the first; the animation's internal name is irrelevant.
+- **Clip-only content** — node hierarchy and animation. Meshes, skins, materials and textures are dead weight.
+- Tracks target the canonical \`${locomotionReference_1.LOCOMOTION_SKELETON}\` bone names. One rotation track per animated bone; only
+  \`pelvis\` (and \`root\`) may carry translation. A track on a bone the skeleton does not have is dropped at
+  binding time, so the clip plays partially or not at all.
+- **Clips must arrive in-place.** The runtime does no root-motion processing: subtract the ground travel and
+  record what you subtracted as \`strideSpeed\`. A clip that still travels slides away from the capsule.
+- Metres and seconds, glTF Y-up.
+
+## The clip vocabulary (gait-only)
+
+Core: \`idle\`, \`walk\`, \`run\`, \`sprint\`, \`crouchIdle\`, \`crouchWalk\`, \`jumpStart\`, \`fall\`, \`land\`.
+Turn-in-place: \`turnL90\`, \`turnR90\`, \`turnL180\`, \`turnR180\` and the \`crouchTurn*\` set (all one-shots).
+Rings: ${locomotionReference_1.RING_GAITS.map((gait) => `\`${gait}\``).join(', ')} each take the suffixes below (e.g. \`${locomotionReference_1.LOCOMOTION_NAME_PREFIX}walkFL\`).
+
+\`death*\`, \`getup*\`, \`sit*\`, \`lie\` and \`hit*\` exist in the platform set but are NOT part of the pack
+vocabulary — the publish gate refuses them.
+
+| Ring suffix | direction (deg) |
+|---|---|
+| *(none)* | 0 (forward, by definition) |
+${ringRows}
+
+A sibling joins the ring only with BOTH a numeric \`strideSpeed\` and a \`direction\`. A partial ring is legal —
+the blend space interpolates between the nearest authored directions.
+
+## \`strideSpeed\` bands
+
+A travelling clip's stride must sit within ${locomotionReference_1.PACK_STRIDE_BAND.minRatio}× – ${locomotionReference_1.PACK_STRIDE_BAND.maxRatio}× of the platform clip it replaces. The runtime
+CLAMPS an out-of-band value; the publish gate REFUSES it. Over the gaits your pack contains,
+${locomotionReference_1.GAIT_LADDER.join(' < ')} must hold.
+
+| Clip | Platform (m/s) | Allowed (m/s) |
+|---|---|---|
+${strideRows}
+
+Every other name (\`idle\`, \`crouchIdle\`, \`jumpStart\`, \`fall\`, \`land\`, every turn clip) must carry
+\`strideSpeed: null\` — a number on one is refused, and a \`null\` on a travelling clip is refused too.
+
+Match the style's natural tempo to the slot: the playback-rate correction stretches a clip by at most ×0.75–1.25,
+so a style slower than the band plays visibly sped-up rather than the world slowing down for it.
+
+## Publication
+
+Run \`helix pack validate .\` before publication. The previous Item-first \`pack publish\` route is
+retired. Seal the clips and add-on definition as a Continuum Package, then use
+\`helix continuum make-item\` with its exact Package pin when the add-on adapter is available.
+`;
+}
+function scaffoldLocomotionPack(input) {
+    const dir = (0, node_path_1.resolve)(input.dir);
+    (0, node_fs_1.mkdirSync)((0, node_path_1.join)(dir, 'anims'), { recursive: true });
+    const metaPath = (0, node_path_1.join)(dir, 'anims', 'clip-meta.json');
+    const readmePath = (0, node_path_1.join)(dir, 'README.md');
+    const created = [];
+    const skipped = [];
+    const write = (path, rel, body) => {
+        if ((0, node_fs_1.existsSync)(path) && input.overwrite !== true) {
+            skipped.push(rel);
+            return;
+        }
+        (0, node_fs_1.writeFileSync)(path, body);
+        created.push(rel);
+    };
+    write(metaPath, 'anims/clip-meta.json', `${JSON.stringify([EXAMPLE_CLIP], null, 2)}\n`);
+    write(readmePath, 'README.md', readmeText());
+    const nextSteps = [
+        `Export ${locomotionReference_1.LOCOMOTION_NAME_PREFIX}walk.glb into anims/ — one animation, in-place, on the ${locomotionReference_1.LOCOMOTION_SKELETON} skeleton.`,
+        'Replace the example entry: "duration" must equal the GLB animation\'s real length, and "strideSpeed" the measured ' +
+            'pre-in-place travel of your own motion (see README.md for the band).',
+        'Add an entry + GLB per further clip you are replacing; every name you omit falls back to the platform clip.',
+        'helix pack validate <dir>',
+        'Seal an add-on Package, then use helix continuum make-item with its exact Package pin.',
+    ];
+    return { dir, metaPath, readmePath, created, skipped, nextSteps };
+}
+//# sourceMappingURL=scaffold.js.map

package/dist/pack/scaffold.js.map

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

package/dist/pack/validate.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Where the pack's meta and its recorded pins live, pack-relative. The pins ride BESIDE the meta rather than
+ * inside it: clip-meta.json is authored (and re-emitted by the pipeline), the pin ledger is publish output.
+ */
+export declare const CLIP_META_FILE = "anims/clip-meta.json";
+export declare const PINS_FILE = "anims/pins.json";
+/** How far the measured GLB length may sit from the declared `duration`, seconds. */
+export declare const DURATION_TOLERANCE_S = 0.05;
+/**
+ * One published clip, as `pack publish` recorded it. `checksumSha256` is the Vault's own answer, kept VERBATIM;
+ * `sourceSha256` is this CLI's digest of the local bytes, and the only thing a re-run compares against.
+ */
+export type PackPin = {
+    assetId: string;
+    version: number;
+    checksumSha256: string;
+    sourceSha256: string;
+    durationSeconds: number;
+    uploadedAt: string;
+};
+export type PackPinFile = {
+    version: 1;
+    clips: Record<string, PackPin>;
+};
+/** One clip-meta entry that survived the schema pass, with what the files said about it. */
+export type PackClip = {
+    /** The full namespaced name, `locomotion.walk` — also the GLB's file name. */
+    name: string;
+    /** The name the `/clips/<bareName>` pointer installs. */
+    bareName: string;
+    /** Pack-relative GLB ref, and its absolute path. */
+    ref: string;
+    file: string;
+    loop: boolean;
+    duration: number;
+    strideSpeed: number | null;
+    direction?: number;
+    /** Measured seconds off the GLB, null when the file is missing or declares no timings. */
+    measuredS: number | null;
+    /** The recorded pin, when `pack publish` has already uploaded these exact bytes. */
+    pin: PackPin | null;
+};
+export type PackValidation = {
+    dir: string;
+    errors: string[];
+    warnings: string[];
+    clips: PackClip[];
+    /** Every clip carries a pin matching its current bytes, so fits/ops can be built for the backend. */
+    pinned: boolean;
+};
+/** The digest a re-run compares against to decide whether a clip still needs uploading. */
+export declare function sourceDigest(bytes: Buffer): string;
+export declare const packPinsPath: (dir: string) => string;
+/** Read `anims/pins.json`, or an empty ledger when the pack has never been published. */
+export declare function readPackPins(dir: string): PackPinFile;
+/** The compatibility contract a locomotion pack declares. The CLI's assertFits demands all four arrays. */
+export declare function buildPackFits(clips: readonly PackClip[]): Record<string, unknown>;
+/**
+ * One `patch`/`set` op per clip — the pack's whole content, since there is no mesh behind it. Throws on a clip
+ * with no usable pin: an op naming nothing is a listing with a price on it.
+ */
+export declare function buildPackOps(clips: readonly PackClip[]): Record<string, unknown>[];
+/**
+ * Validate a pack directory offline. Everything the backend's clip-set gate refuses is refused here too, plus
+ * the two things it never sees: the local GLBs, and whether the declared duration matches their bytes.
+ */
+export declare function validateLocomotionPack(dir: string): PackValidation;