@helix3/helix-cli 0.1.15-helix3.236 → 0.1.15-helix3.237

package/README.md

@@ -64,6 +64,7 @@ The token is stored in `~/.helix/credentials.json` (mode `600`). It's sent as
 | `helix assets credits\|check-loaders` | Render asset credits from provenance and reject models requiring unsupported loaders. |
 | `helix character import <body.glb> [--map <json>] [--fit source\|canonical] [--provenance <json>]` | Convert one self-contained third-party humanoid through the public `helix-humanoid@1` pipeline. The command rejects external/remote resources and resource bombs before parsing, generates bounded LODs, and emits a source/license/transformation/checksum receipt beside the output. `--fit canonical` aligns the rest skeleton/proportions; it does not prove that Base Male-targeted garments fit a different body surface. |
 | `helix character retarget-animation <clip.fbx\|clip.glb>` | Retarget a raw Mixamo/Meshy clip directly to `helix-humanoid@1`. FBX conversion is deterministic and runs inside the CLI; no hidden Blender/DCC pre-export is required. |
+| `helix pack scaffold\|validate\|publish <dir>` | Locomotion packs — the replacement movement clips a player equips as a character add-on in the `character.locomotion@1` clip-set slot. `scaffold` writes `anims/clip-meta.json` plus a README carrying the per-clip contract; `validate` runs the whole gate offline in **one** pass (clip-meta schema, one GLB per entry with exactly one animation, measured length against the declared duration, the gait-only vocabulary, the `strideSpeed` bands, and walk < run < sprint); `publish` uploads each clip GLB as a public Vault animation, records the returned pins in `anims/pins.json`, then publishes the **meshless** add-on whose ops pin those versions — a re-run reuses every unchanged pin, so an interrupted publish resumes. The governing rule of the slot: a pack may change how a walk *looks*; it may never change how far that walk *gets you*. Partial packs are valid products down to a single clip. `--dry-run` stops before any network call and works logged out. |
 | `helix world audit\|source-audit\|perf-gate\|prove-live` | Run the blocking world QA, performance, and deployed-build identity gates. |
 | `helix world performance-report [bundle] [--scene <scene-v2.json>] [--package <package-version.json>] [--snapshot <inspect.json>] [--perf <receipt.json>]` | Analyze exact declared scene resources and existing reference-profile budgets, while keeping authored geometry/material/delivery estimates separate from supplied runtime claims. Prints actionable instancing, Palette, lighting, transfer, and visual-QA guidance; it never predicts FPS from static counts. |
 | `helix world scene-source inventory\|compile <helsinki\|bistro> <archive>` | Verify and safely inventory a known CC BY source archive, then compile deterministic local proxy/detail GLBs and an existing-schema Scene v2 package. |

package/dist/index.js

@@ -1454,7 +1454,7 @@ item
             }
             console.log(`✔ Dry run — nothing uploaded, no fee charged.`);
             console.log(`  POST ${plan.endpoint}`);
-            console.log(`  mesh:      ${plan.mesh.file} (${(plan.mesh.sizeBytes / 1024).toFixed(1)} KiB, ${plan.mesh.contentType})`);
+            console.log(`  mesh:      ${plan.mesh ? `${plan.mesh.file} (${(plan.mesh.sizeBytes / 1024).toFixed(1)} KiB, ${plan.mesh.contentType})` : '(none — the clips are the content)'}`);
             console.log(`  thumbnail: ${plan.thumbnail ? `${plan.thumbnail.file} (${(plan.thumbnail.sizeBytes / 1024).toFixed(1)} KiB, ${plan.thumbnail.contentType})` : '(none — server-rendered)'}`);
             console.log(`  payload:   ${JSON.stringify(plan.payload, null, 2).replace(/\n/g, '\n             ')}`);
             for (const warning of plan.warnings)
@@ -3788,6 +3788,107 @@ itemDef
         fail(err instanceof lib_1.ApiError ? err.render() : `✖ ${err instanceof Error ? err.message : String(err)}`);
     }
 });
+const pack = program
+    .command('pack')
+    .description('Locomotion packs — the replacement movement clips a player equips as a character add-on: scaffold the pack directory, validate it offline, publish it into the character.locomotion@1 slot');
+pack
+    .command('scaffold')
+    .description('Write a starter locomotion pack: anims/clip-meta.json with one example entry, plus a README carrying the per-clip contract the publish gate enforces')
+    .argument('<dir>', 'directory for the new pack (the starter files land in <dir>/anims/)')
+    .option('--overwrite', 'replace files that already exist (default: skip them)')
+    .action(async (dir, opts) => {
+    try {
+        const { scaffoldLocomotionPack } = await Promise.resolve().then(() => __importStar(require('./pack/scaffold')));
+        const result = scaffoldLocomotionPack({ dir, ...(opts.overwrite === true && { overwrite: true }) });
+        console.log(`✔ Created ${result.created.length} file(s) in ${result.dir}`);
+        if (result.skipped.length > 0) {
+            console.log(`  Kept ${result.skipped.length} existing file(s): ${result.skipped.join(', ')}  (--overwrite to replace)`);
+        }
+        console.log(`\nNext steps:\n${result.nextSteps.map((step, index) => `  ${index + 1}. ${step}`).join('\n')}`);
+    }
+    catch (err) {
+        fail(`✖ ${err instanceof Error ? err.message : String(err)}`);
+    }
+});
+pack
+    .command('validate')
+    .description('Validate a locomotion pack offline, reporting EVERY problem in one pass: the clip-meta schema, one GLB per entry with exactly one animation, the measured length against the declared duration, the gait-only vocabulary, the strideSpeed bands and the walk < run < sprint ladder')
+    .argument('<dir>', 'the pack directory (the one containing anims/)')
+    .action(async (dir) => {
+    try {
+        const { validateLocomotionPack } = await Promise.resolve().then(() => __importStar(require('./pack/validate')));
+        const result = validateLocomotionPack(dir);
+        if (result.warnings.length > 0)
+            console.log(`warnings:\n  ${result.warnings.join('\n  ')}`);
+        if (result.errors.length > 0) {
+            fail(`✖ ${result.errors.length} error(s):\n  - ${result.errors.join('\n  - ')}`);
+        }
+        console.log(`✔ valid — ${result.clips.length} clip(s), ${result.clips.filter((clip) => clip.pin !== null).length} already pinned`);
+    }
+    catch (err) {
+        fail(`✖ ${err instanceof Error ? err.message : String(err)}`);
+    }
+});
+pack
+    .command('publish')
+    .description('Publish a validated locomotion pack: upload each clip GLB as a public Vault animation carrying its measured duration, then publish the MESHLESS add-on whose ops pin those versions')
+    .argument('<dir>', 'the pack directory')
+    .option('--title <name>', 'add-on title (default: the pack directory name)')
+    .option('--description <text>', 'store description — say WHICH clips the pack covers; every name it omits keeps the platform motion')
+    .option('--tags <a,b,c>', 'comma-separated search keywords')
+    .option('--dry-run', 'print what WOULD be uploaded and published; no upload, no publish, no fee')
+    .action(async (dir, opts) => {
+    const input = {
+        dir,
+        ...(opts.title !== undefined && { title: opts.title }),
+        ...(opts.description !== undefined && { description: opts.description }),
+        ...(opts.tags !== undefined && { tags: (0, lib_1.parseTags)(opts.tags) }),
+    };
+    // --dry-run stops before ANY network call, so it works logged out — the point is to check the pack and
+    // the metadata, not the account.
+    if (opts.dryRun) {
+        try {
+            const { planPackPublish } = await Promise.resolve().then(() => __importStar(require('./pack/publish')));
+            const plan = planPackPublish(input);
+            console.log('✔ Dry run — nothing uploaded, no fee charged.');
+            console.log(`  ${plan.title} — ${plan.clips.length} clip(s): ${plan.uploads} to upload, ${plan.reused} pin(s) reused`);
+            for (const clip of plan.clips) {
+                const size = `${(clip.sizeBytes / 1024).toFixed(1)} KiB, ${clip.durationSeconds.toFixed(3)}s`;
+                console.log(`  ${clip.action === 'upload' ? '↑' : '='} ${clip.ref} (${size})`);
+            }
+            console.log(`  payload:   ${JSON.stringify(plan.payload, null, 2).replace(/\n/g, '\n             ')}`);
+            for (const warning of plan.warnings)
+                console.log(`  • ${warning}`);
+            const status = (0, lib_1.authStatus)();
+            if (!status.loggedIn)
+                console.log('  • not logged in — run `helix login` before the real publish');
+        }
+        catch (err) {
+            fail(`✖ ${err instanceof Error ? err.message : String(err)}`);
+        }
+        return;
+    }
+    const creds = requireAuth();
+    const mismatch = (0, config_1.credsEnvMismatchWarning)(creds.apiUrl);
+    if (mismatch)
+        fail(`✖ Refusing to publish a locomotion pack:\n${mismatch}`);
+    try {
+        const { publishLocomotionPack } = await Promise.resolve().then(() => __importStar(require('./pack/publish')));
+        const report = await publishLocomotionPack(input, creds, { onProgress: (message) => console.log(`  ${message}`) });
+        const uploaded = report.clips.filter((clip) => clip.uploaded).length;
+        console.log(`✔ Published "${report.item.title}" (${report.item.slug}) — ${report.clips.length} clip(s), ${uploaded} uploaded this run`);
+        for (const clip of report.clips)
+            console.log(`  ${clip.name} → ${clip.assetId}@${clip.version}`);
+        console.log(`  status: ${report.item.status}`);
+        console.log(`  publish fee: ${report.item.publishFeeLix} LIX`);
+        console.log(`  id:     ${report.item.id}`);
+        if (report.warnings.length > 0)
+            console.log(`warnings:\n  ${report.warnings.join('\n  ')}`);
+    }
+    catch (err) {
+        fail(err instanceof lib_1.ApiError ? err.render() : `✖ ${err instanceof Error ? err.message : String(err)}`);
+    }
+});
 const world = program
     .command('world')
     .description("World tools — create the world's identity before publishing, and measure a built world's geometry as data instead of eyeballing screenshots");