@helix3/helix-cli 0.1.14-helix3.219 → 0.1.14-helix3.221

package/README.md

@@ -41,7 +41,7 @@ The token is stored in `~/.helix/credentials.json` (mode `600`). It's sent as
 | `helix logout` | Remove the stored token. |
 | `helix whoami` | Show current login status. |
 | `helix init <dir> [--kind character\|multiplayer\|scene]` | Scaffold a complete, build-ready Vite + TypeScript world. `--kind scene` emits a multiplayer world whose ENVIRONMENT is a sealed HELIX Scene v2 document — the starter document is compiled offline into `public/scene/mall/`, pinned in `public/helix.json`'s `scene` field, kept out of the bundle by `public/.helixignore`, and lit by `public/helix.visuals.json` through the `scene` + `visual` system pins. |
-| `helix install [--update]` | Resolve a world's `systems`/`abilities` pins (a v0.2 **or v0.3** manifest) → materialize the modules, the `three` import map, and `helix.runtime.ts`. |
+| `helix install [--update] [--asset-pack <slug@range>]` | Resolve a world's `systems`/`abilities` pins (a v0.2 **or v0.3** manifest) → materialize the modules, the `three` import map, and `helix.runtime.ts`. Repeat `--asset-pack` to constrain specific system assets for this resolution. |
 | `helix validate [dir]` | Validate a bundle locally — the exact rules the server enforces. |
 | `helix publish [dir] [--thumbnail <file>] [--upload-source] [--source-dir <path>]` | Validate → resolve/create the world → upload files → finalize → set the cover image → print the play URL. `--upload-source` additionally sends the project's source through a separate private channel so the world can be edited on the website later — **off by default**. |
 | `helix list` | List your worlds. |
@@ -73,6 +73,36 @@ The token is stored in `~/.helix/credentials.json` (mode `600`). It's sent as
 | `helix unreal publish <candidate> --world <slug>` | Upload a **cooked** Unreal world to HELIX: verify the candidate, presign, upload every artifact, finalize, and promote it as the world's active build. |
 | `helix doctor [--project <dir>]` | Print the environment + whether the @helix toolchain (CLI/MCP/SDK/manifest) is current. |
 
+### Constraining system assets during installation
+
+To update system code while deliberately selecting a compatible asset version:
+
+```bash
+# With an exact system pin in helix.json, e.g. humanoid-character: "0.2.65"
+helix install --update --asset-pack humanoid-character-assets@0.1.4
+```
+
+`--asset-pack <slug@range>` is repeatable for different asset slugs. Supported ranges
+are exact versions, `^`/`~` ranges (partial versions are padded as for system pins),
+`latest`, and `*`. Resolution selects the highest active version satisfying both
+the explicit constraint and the system envelope's asset requirement. Complete exact
+pins use the authoritative public version-detail endpoint, including active staged
+versions. Incorrect kinds/identities, unused slugs, duplicates, invalid ranges,
+missing versions, and incompatible constraints fail before installer writes.
+
+These constraints apply to **this invocation**. An existing lock requires `--update`;
+a fresh install can use the option without a lock. The installer resolves from the
+catalog and writes the exact asset URL/version and unchanged envelope `range` into
+the lock, with invocation intent recorded in top-level `assetPackConstraints`.
+It does not reuse unverified asset metadata
+from an old lock. Normal `helix install` then replays that generated lock as usual.
+
+A subsequent `helix install --update` without the option refreshes all dependencies
+from their ordinary requirements, including previously constrained assets. Repeat the
+option in your update command to retain the constraint. It is not a world manifest
+field or a permanent asset freeze, and cannot be combined with local first-party
+installation. Generated locks, import maps and runtime modules remain installer-owned.
+
 ## Unreal runtime projects
 
 `helix unreal init <project> --mode shared-runtime|native-game` creates `helix.unreal.json`.

package/dist/index.js

@@ -671,6 +671,7 @@ program
     .description("Resolve this v0.2 world's system/ability pins, download their code, and write installed.json + helix.lock.json")
     .argument('[path]', 'a local ability bundle to copy in (requires --first-party); omit for the world resolve+install')
     .option('--update', 're-resolve pins against the live catalog and rewrite the lock (else the existing lock is replayed)')
+    .option('--asset-pack <slug@range>', 'constrain a system asset-pack for this resolution (repeatable; existing lock requires --update)', (value, previous) => [...previous, value], [])
     .option('--first-party', 'FIRST-PARTY only: copy the local <path> bundle (code AND clips) into helix_modules — for engine devs testing co-located assets')
     .option('--local', 'alias of --first-party (deprecated)')
     .option('--api-url <url>', 'platform API base URL (default: the environment you are logged in to)')
@@ -684,6 +685,8 @@ program
     opts.apiUrl = opts.apiUrl ?? (0, config_1.loadCredentials)()?.apiUrl ?? config_1.DEFAULT_API_URL;
     const firstParty = Boolean(opts.firstParty || opts.local);
     if (path !== undefined || firstParty) {
+        if (opts.assetPack?.length)
+            fail('✖ --asset-pack is only supported for world pin resolution');
         if (!path) {
             fail('✖ --first-party needs a bundle path: helix install <bundle> --first-party');
         }
@@ -704,9 +707,20 @@ program
         return;
     }
     try {
+        const assetPacks = Object.create(null);
+        for (const value of opts.assetPack ?? []) {
+            const at = value.indexOf('@');
+            if (at <= 0 || at === value.length - 1)
+                throw new Error('--asset-pack requires <slug@range>');
+            const slug = value.slice(0, at);
+            if (Object.hasOwn(assetPacks, slug))
+                throw new Error(`duplicate asset-pack constraint "${slug}"`);
+            assetPacks[slug] = value.slice(at + 1);
+        }
         const result = await (0, lib_1.installWorld)(process.cwd(), {
             apiUrl: opts.apiUrl,
             update: opts.update,
+            assetPacks,
             onProgress: (msg) => console.log(msg),
         });
         const sys = result.systems.map((s) => `${s.slug}@${s.version}`).join(', ') || '(none)';