@helix3/helix-cli 0.1.4-helix3.24

package/dist/install.js

@@ -0,0 +1,201 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RUNTIME_MODULE = exports.LOCKFILE = exports.INSTALLED_INDEX = exports.MODULES_DIR = void 0;
+exports.installWorld = installWorld;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const ability_1 = require("./ability");
+const resolve_1 = require("./resolve");
+// `helix install` for a v0.2 world (consumer-plan decisions #2/#4/#8). Resolves the helix.json
+// system/ability pins to exact versions, downloads CODE ONLY into public/helix_modules/<slug>/
+// (assets always stream from the CDN — §11), and writes the v2 installed.json the runtime loader
+// reads. The full resolution is locked in helix.lock.json: a bare re-run replays the lock (never
+// re-resolves), `--update` re-resolves the live catalog and rewrites the lock.
+exports.MODULES_DIR = 'helix_modules';
+exports.INSTALLED_INDEX = 'installed.json';
+exports.LOCKFILE = 'helix.lock.json';
+exports.RUNTIME_MODULE = 'helix.runtime.ts'; // generated under src/
+// The import map between these markers in index.html is (re)written by install with the resolved
+// platform runtime URL, so the world's bare `three` resolves to the single hosted instance.
+const IMPORTMAP_BLOCK = /(<!--\s*helix:three:start\s*-->)[\s\S]*?(<!--\s*helix:three:end\s*-->)/;
+// Belt-and-suspenders: the server already splits code from assets, but a code channel must never
+// carry a clip/texture/sound — that would put a HELIX asset on the consumer's disk.
+const ASSET_EXT = /\.(glb|gltf|bin|ktx2|png|jpe?g|webp|mp3|ogg|wav)$/i;
+const WORLD_MANIFEST_LOCATIONS = ['helix.json', (0, node_path_1.join)('public', 'helix.json')];
+function readWorldManifest(worldDir) {
+    const manifestPath = WORLD_MANIFEST_LOCATIONS.map((rel) => (0, node_path_1.join)(worldDir, rel)).find((p) => (0, node_fs_1.existsSync)(p));
+    if (!manifestPath) {
+        throw new Error(`no helix.json found (looked in ./ and ./public/) — run \`helix install\` from a world project, or \`helix install <bundle> --first-party\` for a local ability`);
+    }
+    let manifest;
+    try {
+        manifest = JSON.parse((0, node_fs_1.readFileSync)(manifestPath, 'utf8'));
+    }
+    catch (err) {
+        throw new Error(`${manifestPath} is not valid JSON: ${err instanceof Error ? err.message : err}`);
+    }
+    if (manifest.helixVersion !== '0.2' && manifest.helixVersion !== '0.3') {
+        throw new Error(`helix install resolves system/ability pins from a v0.2+ manifest, but ${manifestPath} is helixVersion "${manifest.helixVersion ?? '0.1'}" — set "helixVersion" to "0.2" or "0.3" with "systems"/"abilities" maps`);
+    }
+    return { manifestPath, pins: { systems: manifest.systems ?? {}, abilities: manifest.abilities ?? {} } };
+}
+// A bare re-run must replay the existing lock verbatim; it may only do so when helix.json hasn't
+// drifted. Any added/removed pin, a changed range, or an out-of-range locked version means the
+// lock is stale and the user must opt into re-resolving with --update.
+function verifyLockMatchesPins(lock, pins, satisfies) {
+    const want = new Map();
+    for (const [slug, range] of Object.entries(pins.systems ?? {}))
+        want.set(slug, range);
+    for (const [slug, range] of Object.entries(pins.abilities ?? {}))
+        want.set(slug, range);
+    const have = new Map([...lock.systems, ...lock.abilities].map((p) => [p.slug, p]));
+    const drift = [];
+    for (const [slug, range] of want) {
+        const locked = have.get(slug);
+        if (!locked)
+            drift.push(`${slug} is newly pinned (${range})`);
+        else if (locked.range !== range)
+            drift.push(`${slug} pinned ${range}, lock has ${locked.range}`);
+        else if (!satisfies(locked.version, (0, resolve_1.normalizePinRange)(range)))
+            drift.push(`${slug}@${locked.version} no longer satisfies ${range}`);
+    }
+    for (const slug of have.keys())
+        if (!want.has(slug))
+            drift.push(`${slug} is in the lock but no longer pinned`);
+    if (drift.length) {
+        throw new Error(`helix.json pins differ from ${exports.LOCKFILE} — run \`helix install --update\` to re-resolve:\n${drift.map((d) => `  - ${d}`).join('\n')}`);
+    }
+}
+function assertCodeOnly(pkg) {
+    const leaked = pkg.codeFiles.filter((f) => ASSET_EXT.test(f));
+    if (leaked.length) {
+        throw new Error(`refusing to install ${pkg.slug}: asset files in its code channel (assets must stream from the CDN): ${leaked.join(', ')}`);
+    }
+}
+async function defaultDownload(codeBaseUrl, files, destDir) {
+    const base = codeBaseUrl.replace(/\/+$/, '');
+    for (const rel of files) {
+        const res = await fetch(`${base}/${rel}`);
+        if (!res.ok)
+            throw new Error(`could not download ${rel} from ${base} (${res.status} ${res.statusText})`);
+        const dest = (0, node_path_1.join)(destDir, rel);
+        (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(dest), { recursive: true });
+        (0, node_fs_1.writeFileSync)(dest, Buffer.from(await res.arrayBuffer()));
+    }
+}
+// The platform CDN base is the resolved code URL up to /packages/ — the hosted runtime lives at
+// <base>/runtime/ on the same CDN. Deriving it from a real resolved URL means install never needs
+// the base hardcoded or a separate endpoint.
+function cdnRootFrom(url) {
+    const i = url.indexOf('/packages/');
+    return i > 0 ? url.slice(0, i) : null;
+}
+// Point the world at the single hosted three: rewrite index.html's import map and (re)generate
+// src/helix.runtime.ts (the three module URL, KTX2 transcoder path, and the system's CDN asset
+// base) for main.ts to import. Returns null when no system is pinned (nothing imports three by version).
+function wireRuntime(worldDir, resolution, onProgress) {
+    const system = resolution.systems.find((s) => s.three);
+    if (!system || !system.three)
+        return null;
+    const cdnRoot = cdnRootFrom(system.codeUrl);
+    if (!cdnRoot)
+        throw new Error(`cannot derive the platform CDN base from "${system.codeUrl}" (expected a /packages/ path)`);
+    const threeVersion = system.three;
+    const threeModuleUrl = `${cdnRoot}/runtime/three/${threeVersion}/three.module.js`;
+    const transcoderPath = `${cdnRoot}/runtime/basis/three-${threeVersion}/`;
+    const htmlPath = (0, node_path_1.join)(worldDir, 'index.html');
+    if ((0, node_fs_1.existsSync)(htmlPath)) {
+        const html = (0, node_fs_1.readFileSync)(htmlPath, 'utf8');
+        if (IMPORTMAP_BLOCK.test(html)) {
+            const block = `$1\n    <script type="importmap">\n    { "imports": { "three": "${threeModuleUrl}" } }\n    </script>\n    $2`;
+            (0, node_fs_1.writeFileSync)(htmlPath, html.replace(IMPORTMAP_BLOCK, block));
+        }
+        else {
+            onProgress('! index.html has no <!-- helix:three:start/end --> markers — import map not written');
+        }
+    }
+    const runtimeTs = [
+        '// GENERATED by `helix install` — do not edit; re-run install to update.',
+        `export const THREE_VERSION = ${JSON.stringify(threeVersion)};`,
+        `export const THREE_MODULE_URL = ${JSON.stringify(threeModuleUrl)};`,
+        `export const TRANSCODER_PATH = ${JSON.stringify(transcoderPath)};`,
+        `export const SYSTEM_ASSET_BASE = ${JSON.stringify(system.assetBaseUrl ?? '')};`,
+        '',
+    ].join('\n');
+    const srcDir = (0, node_path_1.join)(worldDir, 'src');
+    (0, node_fs_1.mkdirSync)(srcDir, { recursive: true });
+    (0, node_fs_1.writeFileSync)((0, node_path_1.join)(srcDir, exports.RUNTIME_MODULE), runtimeTs);
+    return { threeVersion, threeModuleUrl, transcoderPath };
+}
+async function defaultDeps(apiUrl) {
+    const validator = await (0, ability_1.loadVendoredValidator)();
+    const indexValidator = await (0, ability_1.loadInstalledIndexValidator)();
+    if (!validator.satisfiesSystemPin)
+        throw new Error('vendored validator is missing satisfiesSystemPin — re-vendor ability-manifest.mjs');
+    const satisfies = validator.satisfiesSystemPin;
+    return {
+        resolve: (pins) => (0, resolve_1.resolvePins)(apiUrl, pins),
+        download: defaultDownload,
+        satisfies,
+        validateIndex: (value) => indexValidator.validateInstalledIndex(value),
+    };
+}
+async function installWorld(worldDir, opts) {
+    const onProgress = opts.onProgress ?? (() => undefined);
+    const deps = opts.deps ?? (await defaultDeps(opts.apiUrl));
+    const { manifestPath, pins } = readWorldManifest(worldDir);
+    const lockPath = (0, node_path_1.join)(worldDir, exports.LOCKFILE);
+    let resolution;
+    let reresolved;
+    if (!opts.update && (0, node_fs_1.existsSync)(lockPath)) {
+        const lock = JSON.parse((0, node_fs_1.readFileSync)(lockPath, 'utf8'));
+        verifyLockMatchesPins(lock, pins, deps.satisfies);
+        resolution = { systems: lock.systems, abilities: lock.abilities };
+        reresolved = false;
+        onProgress(`Replaying ${exports.LOCKFILE} (run with --update to re-resolve)`);
+    }
+    else {
+        onProgress(opts.update ? 'Re-resolving pins against the live catalog' : 'Resolving pins');
+        resolution = await deps.resolve(pins);
+        const lock = { lockfileVersion: 1, systems: resolution.systems, abilities: resolution.abilities };
+        (0, node_fs_1.writeFileSync)(lockPath, `${JSON.stringify(lock, null, 2)}\n`);
+        reresolved = true;
+    }
+    const all = [...resolution.systems, ...resolution.abilities];
+    all.forEach(assertCodeOnly);
+    // Clean rebuild of the managed dir so a re-run is byte-deterministic (no orphaned stale code).
+    const modulesDir = (0, node_path_1.join)(worldDir, 'public', exports.MODULES_DIR);
+    (0, node_fs_1.rmSync)(modulesDir, { recursive: true, force: true });
+    (0, node_fs_1.mkdirSync)(modulesDir, { recursive: true });
+    for (const pkg of all) {
+        onProgress(`Downloading ${pkg.slug}@${pkg.version} (${pkg.codeFiles.length} code files)`);
+        await deps.download(pkg.codeUrl, pkg.codeFiles, (0, node_path_1.join)(modulesDir, pkg.slug));
+    }
+    // Only abilities go in installed.json — the system is build-time-embedded via the alias. codeUrl is
+    // the ability's dir RELATIVE to the index base (just the slug); the loader resolves it against the
+    // base the world passes (document-derived), so a published world works from any deployment sub-path
+    // — a root-absolute "/helix_modules/<id>" would 404 once the world isn't at the origin root. Clips
+    // stream from the CDN assetBaseUrl.
+    const entries = resolution.abilities
+        .map((ab) => {
+        if (!ab.assetBaseUrl)
+            throw new Error(`ability "${ab.slug}" has no CDN asset base — cannot write a v2 installed.json entry`);
+        return { id: ab.slug, version: ab.version, codeUrl: ab.slug, assetBaseUrl: ab.assetBaseUrl };
+    })
+        .sort((a, b) => a.id.localeCompare(b.id));
+    const issues = deps.validateIndex(entries);
+    if (issues.length) {
+        throw new Error(`generated installed.json failed validation:\n${issues.map((i) => `  ${i.path || '(root)'}: ${i.message}`).join('\n')}`);
+    }
+    (0, node_fs_1.writeFileSync)((0, node_path_1.join)(modulesDir, exports.INSTALLED_INDEX), `${JSON.stringify(entries, null, 2)}\n`);
+    const runtime = wireRuntime(worldDir, resolution, onProgress);
+    return {
+        manifestPath,
+        modulesDir,
+        systems: resolution.systems.map((s) => ({ slug: s.slug, version: s.version })),
+        abilities: resolution.abilities.map((a) => ({ slug: a.slug, version: a.version })),
+        reresolved,
+        runtime,
+    };
+}
+//# sourceMappingURL=install.js.map

package/dist/install.js.map

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

package/dist/lib.d.ts

@@ -0,0 +1,88 @@
+import { HelixApi } from './api';
+import { CliCredentials } from './config';
+export { ApiError, HelixApi, uploadToTicket } from './api';
+export { checkBundle, multiplayerConfigBundleFile, MULTIPLAYER_CONFIG_FILENAME, type BundleCheck, type BundleFile, } from './bundle';
+export { checkPackageBundle, type PackageBundleCheck } from './package';
+export { checkAbilityBundle, installLocalAbility, loadVendoredValidator, loadInstalledIndexValidator, type AbilityValidator, } from './ability';
+export { normalizePinRange, resolvePins, type PinMap, type ResolveDeps, type ResolvedPackage, type ResolvedPins, type VersionDetail, type WorldPins, } from './resolve';
+export { installWorld, INSTALLED_INDEX, LOCKFILE, MODULES_DIR, type InstalledEntry, type InstallDeps, type InstallWorldOptions, type InstallWorldResult, type WorldLock, } from './install';
+export { DEFAULT_API_URL, DEFAULT_WEB_URL, HELIX_ENV, HELIX_SCOPE, loadCredentials, saveCredentials, clearCredentials, jwtExpiresAtIso, type CliCredentials, } from './config';
+export { initTemplate } from './init';
+export { initAbilityTemplate } from './initAbility';
+export type { ImportCharacterClipResult, ImportCharacterOptions, ImportCharacterResult, } from './character/importCharacter';
+import type { ImportCharacterOptions, ImportCharacterResult } from './character/importCharacter';
+export declare function importCharacter(opts: ImportCharacterOptions): Promise<ImportCharacterResult>;
+export type PublishResult = {
+    slug: string;
+    title: string;
+    buildId: string;
+    buildNumber: number;
+    playUrl: string | null;
+    worldUrl: string;
+};
+export type PublishProgress = (message: string) => void;
+type WorldSummary = {
+    id: string;
+    slug: string;
+    title: string;
+    status: string;
+    hasActiveBuild: boolean;
+};
+export declare function publishWorld(root: string, creds: CliCredentials, onProgress?: PublishProgress): Promise<PublishResult>;
+export type PublishPackageResult = {
+    kind: string;
+    slug: string;
+    version: string;
+    revision: number;
+    codeBaseUrl: string;
+    assetBaseUrl: string | null;
+};
+export declare function publishPackage(root: string, creds: CliCredentials, onProgress?: PublishProgress): Promise<PublishPackageResult>;
+export type CatalogPackage = {
+    kind: string;
+    slug: string;
+    title: string;
+    description: string | null;
+    latestVersion: string | null;
+    targetSystem: {
+        id: string;
+        range: string | null;
+    } | null;
+};
+export type CatalogList = {
+    data: CatalogPackage[];
+    pageInfo: {
+        hasNextPage: boolean;
+        nextCursor: string | null;
+    };
+};
+export declare function listPackages(apiUrl: string, kind?: string, system?: string): Promise<CatalogList>;
+export declare function getPackageManifest(apiUrl: string, slug: string, version?: string): Promise<Record<string, unknown>>;
+export declare function authStatus(): {
+    loggedIn: boolean;
+    username?: string;
+    apiUrl?: string;
+    expiresAt?: string;
+};
+export type WhoAmI = {
+    id: string;
+    username: string;
+};
+export declare function whoAmI(api: HelixApi): Promise<WhoAmI>;
+export declare function listMyWorlds(creds: CliCredentials): Promise<WorldSummary[]>;
+export declare const TOOLCHAIN_PACKAGES: string[];
+export type ToolchainStatus = {
+    name: string;
+    installed: string | null;
+    latest: string | null;
+    status: 'current' | 'update-available' | 'unknown';
+    updateHint: string;
+};
+export declare function compareVersions(a: string, b: string): number;
+export declare function cliVersion(): string;
+export declare function installHint(slot: string, scope: string): string;
+export declare function checkForUpdates(opts?: {
+    projectDir?: string;
+    installed?: Record<string, string>;
+    scope?: string;
+}): Promise<ToolchainStatus[]>;

package/dist/lib.js

@@ -0,0 +1,347 @@
+"use strict";
+// Programmatic API for everything the `helix` bin does — also the surface an
+// MCP server calls so AI agents run the exact same code paths as humans.
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TOOLCHAIN_PACKAGES = exports.initAbilityTemplate = exports.initTemplate = exports.jwtExpiresAtIso = exports.clearCredentials = exports.saveCredentials = exports.loadCredentials = exports.HELIX_SCOPE = exports.HELIX_ENV = exports.DEFAULT_WEB_URL = exports.DEFAULT_API_URL = exports.MODULES_DIR = exports.LOCKFILE = exports.INSTALLED_INDEX = exports.installWorld = exports.resolvePins = exports.normalizePinRange = exports.loadInstalledIndexValidator = exports.loadVendoredValidator = exports.installLocalAbility = exports.checkAbilityBundle = exports.checkPackageBundle = exports.MULTIPLAYER_CONFIG_FILENAME = exports.multiplayerConfigBundleFile = exports.checkBundle = exports.uploadToTicket = exports.HelixApi = exports.ApiError = void 0;
+exports.importCharacter = importCharacter;
+exports.publishWorld = publishWorld;
+exports.publishPackage = publishPackage;
+exports.listPackages = listPackages;
+exports.getPackageManifest = getPackageManifest;
+exports.authStatus = authStatus;
+exports.whoAmI = whoAmI;
+exports.listMyWorlds = listMyWorlds;
+exports.compareVersions = compareVersions;
+exports.cliVersion = cliVersion;
+exports.installHint = installHint;
+exports.checkForUpdates = checkForUpdates;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const api_1 = require("./api");
+const bundle_1 = require("./bundle");
+const package_1 = require("./package");
+const ability_1 = require("./ability");
+const config_1 = require("./config");
+var api_2 = require("./api");
+Object.defineProperty(exports, "ApiError", { enumerable: true, get: function () { return api_2.ApiError; } });
+Object.defineProperty(exports, "HelixApi", { enumerable: true, get: function () { return api_2.HelixApi; } });
+Object.defineProperty(exports, "uploadToTicket", { enumerable: true, get: function () { return api_2.uploadToTicket; } });
+var bundle_2 = require("./bundle");
+Object.defineProperty(exports, "checkBundle", { enumerable: true, get: function () { return bundle_2.checkBundle; } });
+Object.defineProperty(exports, "multiplayerConfigBundleFile", { enumerable: true, get: function () { return bundle_2.multiplayerConfigBundleFile; } });
+Object.defineProperty(exports, "MULTIPLAYER_CONFIG_FILENAME", { enumerable: true, get: function () { return bundle_2.MULTIPLAYER_CONFIG_FILENAME; } });
+var package_2 = require("./package");
+Object.defineProperty(exports, "checkPackageBundle", { enumerable: true, get: function () { return package_2.checkPackageBundle; } });
+var ability_2 = require("./ability");
+Object.defineProperty(exports, "checkAbilityBundle", { enumerable: true, get: function () { return ability_2.checkAbilityBundle; } });
+Object.defineProperty(exports, "installLocalAbility", { enumerable: true, get: function () { return ability_2.installLocalAbility; } });
+Object.defineProperty(exports, "loadVendoredValidator", { enumerable: true, get: function () { return ability_2.loadVendoredValidator; } });
+Object.defineProperty(exports, "loadInstalledIndexValidator", { enumerable: true, get: function () { return ability_2.loadInstalledIndexValidator; } });
+var resolve_1 = require("./resolve");
+Object.defineProperty(exports, "normalizePinRange", { enumerable: true, get: function () { return resolve_1.normalizePinRange; } });
+Object.defineProperty(exports, "resolvePins", { enumerable: true, get: function () { return resolve_1.resolvePins; } });
+var install_1 = require("./install");
+Object.defineProperty(exports, "installWorld", { enumerable: true, get: function () { return install_1.installWorld; } });
+Object.defineProperty(exports, "INSTALLED_INDEX", { enumerable: true, get: function () { return install_1.INSTALLED_INDEX; } });
+Object.defineProperty(exports, "LOCKFILE", { enumerable: true, get: function () { return install_1.LOCKFILE; } });
+Object.defineProperty(exports, "MODULES_DIR", { enumerable: true, get: function () { return install_1.MODULES_DIR; } });
+var config_2 = require("./config");
+Object.defineProperty(exports, "DEFAULT_API_URL", { enumerable: true, get: function () { return config_2.DEFAULT_API_URL; } });
+Object.defineProperty(exports, "DEFAULT_WEB_URL", { enumerable: true, get: function () { return config_2.DEFAULT_WEB_URL; } });
+Object.defineProperty(exports, "HELIX_ENV", { enumerable: true, get: function () { return config_2.HELIX_ENV; } });
+Object.defineProperty(exports, "HELIX_SCOPE", { enumerable: true, get: function () { return config_2.HELIX_SCOPE; } });
+Object.defineProperty(exports, "loadCredentials", { enumerable: true, get: function () { return config_2.loadCredentials; } });
+Object.defineProperty(exports, "saveCredentials", { enumerable: true, get: function () { return config_2.saveCredentials; } });
+Object.defineProperty(exports, "clearCredentials", { enumerable: true, get: function () { return config_2.clearCredentials; } });
+Object.defineProperty(exports, "jwtExpiresAtIso", { enumerable: true, get: function () { return config_2.jwtExpiresAtIso; } });
+var init_1 = require("./init");
+Object.defineProperty(exports, "initTemplate", { enumerable: true, get: function () { return init_1.initTemplate; } });
+var initAbility_1 = require("./initAbility");
+Object.defineProperty(exports, "initAbilityTemplate", { enumerable: true, get: function () { return initAbility_1.initAbilityTemplate; } });
+// Character import (`helix character import`) as a programmatic API. The implementation pulls in
+// gltf-transform + meshoptimizer (~165ms of require time), so it is loaded lazily at call time —
+// requiring lib.js (and therefore `helix --help`) stays fast.
+async function importCharacter(opts) {
+    const mod = await Promise.resolve().then(() => __importStar(require('./character/importCharacter')));
+    return mod.importCharacter(opts);
+}
+const UPLOAD_CONCURRENCY = 6;
+// Validate + resolve-or-create world + upload + finalize. Throws ApiError /
+// Error with human-readable messages on any failure.
+async function publishWorld(root, creds, onProgress = () => undefined) {
+    const bundle = (0, bundle_1.checkBundle)(root);
+    if (bundle.errors.length) {
+        throw new Error(`Bundle is invalid:\n${bundle.errors.map((e) => `  - ${e}`).join('\n')}`);
+    }
+    const manifest = bundle.manifest;
+    // Emit the runtime multiplayer config (multiplayer.json) into the bundle for multiplayer worlds. It's
+    // generated in-memory from the validated manifest — the authoritative copy — so drop any hand-placed
+    // one first, keeping exactly one entry. The backend signs its URL into the room credential (configUrl).
+    const multiplayerFile = (0, bundle_1.multiplayerConfigBundleFile)(root, manifest);
+    if (multiplayerFile) {
+        bundle.files = bundle.files.filter((f) => f.path !== bundle_1.MULTIPLAYER_CONFIG_FILENAME);
+        bundle.files.push(multiplayerFile);
+    }
+    const api = api_1.HelixApi.forCredentials(creds);
+    const mine = await api.request('GET', '/api/v1/instant-worlds/me');
+    let world = mine.data.find((w) => w.slug === manifest.slug);
+    if (!world) {
+        onProgress(`Creating world "${manifest.title}" (${manifest.slug})`);
+        world = await api.requestItem('POST', '/api/v1/instant-worlds', {
+            title: manifest.title,
+            slug: manifest.slug,
+        });
+    }
+    onProgress(`Requesting upload for ${bundle.files.length} files`);
+    const build = await api.requestItem('POST', `/api/v1/instant-worlds/${world.id}/builds`, {
+        manifest,
+        files: bundle.files.map((f) => ({ path: f.path, size: f.size })),
+    });
+    let done = 0;
+    const queue = [...build.uploads];
+    await Promise.all(Array.from({ length: UPLOAD_CONCURRENCY }, async () => {
+        for (let ticket = queue.shift(); ticket; ticket = queue.shift()) {
+            const file = bundle.files.find((f) => f.path === ticket.path);
+            // Generated files (multiplayer.json) carry in-memory content; on-disk files are read by path.
+            await (0, api_1.uploadToTicket)(ticket.url, file.content ?? (0, node_fs_1.readFileSync)(file.absolutePath), ticket.contentType, ticket.cacheControl);
+            done += 1;
+            onProgress(`Uploaded ${done}/${build.uploads.length}`);
+        }
+    }));
+    onProgress('Finalizing');
+    await api.request('POST', `/api/v1/instant-worlds/${world.id}/builds/${build.buildId}/finalize`);
+    const detail = await api.requestItem('GET', `/api/v1/instant-worlds/${manifest.slug}`);
+    return {
+        slug: manifest.slug,
+        title: manifest.title,
+        buildId: build.buildId,
+        buildNumber: build.buildNumber,
+        playUrl: detail.playUrl,
+        worldUrl: `${creds.apiUrl}/api/v1/instant-worlds/${manifest.slug}`,
+    };
+}
+// Validate the bundle → create the version (presigned tickets per code/asset
+// channel) → upload → finalize. Admin-only on the server.
+async function publishPackage(root, creds, onProgress = () => undefined) {
+    const validator = await (0, ability_1.loadVendoredValidator)();
+    const check = (0, package_1.checkPackageBundle)(root, validator);
+    if (check.errors.length || !check.envelope) {
+        throw new Error(`Bundle is invalid:\n${check.errors.map((e) => `  - ${e}`).join('\n')}`);
+    }
+    const envelope = check.envelope;
+    const api = api_1.HelixApi.forCredentials(creds);
+    onProgress(`Publishing ${envelope.kind} "${envelope.title}" (${envelope.slug}@${envelope.version}) — ${check.files.length} files`);
+    const created = await api.requestItem('POST', `/api/v1/instant-packages/${envelope.slug}/versions`, {
+        manifest: envelope,
+        payload: check.payload ?? undefined,
+        files: check.files.map((f) => ({ path: f.path, size: f.size })),
+    });
+    let done = 0;
+    const queue = [...created.uploads];
+    await Promise.all(Array.from({ length: UPLOAD_CONCURRENCY }, async () => {
+        for (let ticket = queue.shift(); ticket; ticket = queue.shift()) {
+            const file = check.files.find((f) => f.path === ticket.path);
+            await (0, api_1.uploadToTicket)(ticket.url, (0, node_fs_1.readFileSync)(file.absolutePath), ticket.contentType, ticket.cacheControl);
+            done += 1;
+            onProgress(`Uploaded ${done}/${created.uploads.length}`);
+        }
+    }));
+    onProgress('Finalizing');
+    const final = await api.requestItem('POST', `/api/v1/instant-packages/${envelope.slug}/versions/${encodeURIComponent(envelope.version)}/finalize`);
+    return {
+        kind: final.kind,
+        slug: final.slug,
+        version: final.version,
+        revision: final.revision,
+        codeBaseUrl: final.codeBaseUrl,
+        assetBaseUrl: final.assetBaseUrl,
+    };
+}
+// Public discovery — no auth. List published systems/abilities/asset-packs.
+function listPackages(apiUrl, kind, system) {
+    const api = new api_1.HelixApi(apiUrl);
+    const qs = new URLSearchParams();
+    if (kind)
+        qs.set('kind', kind);
+    if (system)
+        qs.set('system', system);
+    const query = qs.toString();
+    return api.request('GET', `/api/v1/instant-packages${query ? `?${query}` : ''}`);
+}
+// Public discovery — the full manifest + payload (the documentation an agent
+// reads before configuring). `version` defaults to the highest active semver.
+function getPackageManifest(apiUrl, slug, version = 'latest') {
+    const api = new api_1.HelixApi(apiUrl);
+    return api.requestItem('GET', `/api/v1/instant-packages/${slug}/versions/${encodeURIComponent(version)}`);
+}
+// Convenience for tools: current login state without throwing.
+function authStatus() {
+    const creds = (0, config_1.loadCredentials)();
+    if (!creds)
+        return { loggedIn: false };
+    return {
+        loggedIn: true,
+        username: creds.username,
+        apiUrl: creds.apiUrl,
+        expiresAt: creds.expiresAt || undefined,
+    };
+}
+// Validates a token and returns the authenticated user (the CLI's whoami).
+async function whoAmI(api) {
+    return api.requestItem('GET', '/api/v1/users/me');
+}
+async function listMyWorlds(creds) {
+    const api = api_1.HelixApi.forCredentials(creds);
+    const res = await api.request('GET', '/api/v1/instant-worlds/me');
+    return res.data;
+}
+// --- Toolchain version / update checks --------------------------------------
+// The @helix packages an agent's toolchain is built from: the CLI + MCP (tools,
+// ideally run via `npx -y <pkg>@latest`) and manifest + sdk (libs a
+// world/ability project pins).
+// TS imports always use the @hypersoniclabs keys (staging is npm-aliased UNDER
+// those paths); the registry name / latest lookup / update hint use the scope THIS
+// build ships under (HELIX_SCOPE) — so a staging build reports @helixdev/*.
+const TOOLCHAIN_SLOTS = ['helix-cli', 'helix-manifest', 'helix-sdk', 'helix-mcp'];
+const IMPORT_SCOPE = '@hypersoniclabs';
+exports.TOOLCHAIN_PACKAGES = TOOLCHAIN_SLOTS.map((s) => `${IMPORT_SCOPE}/${s}`);
+const REGISTRY = 'https://registry.npmjs.org';
+const isLib = (slot) => slot === 'helix-manifest' || slot === 'helix-sdk';
+// Order by semver core (major.minor.patch); on a tie, a release outranks a prerelease
+// of the same core, and among prereleases the trailing run number breaks the tie
+// (…-staging.14 < …-staging.15) so staging staleness is detectable.
+function compareVersions(a, b) {
+    const core = (v) => v.split('-')[0].split('.').map((n) => Number(n) || 0);
+    const [pa, pb] = [core(a), core(b)];
+    for (let i = 0; i < 3; i++) {
+        if ((pa[i] ?? 0) !== (pb[i] ?? 0))
+            return (pa[i] ?? 0) < (pb[i] ?? 0) ? -1 : 1;
+    }
+    const pre = (v) => (v.includes('-') ? v.slice(v.indexOf('-') + 1) : null);
+    const [ra, rb] = [pre(a), pre(b)];
+    if (ra === rb)
+        return 0;
+    if (ra === null)
+        return 1;
+    if (rb === null)
+        return -1;
+    const run = (s) => {
+        const m = s.match(/(\d+)\s*$/);
+        return m ? Number(m[1]) : 0;
+    };
+    const [oa, ob] = [run(ra), run(rb)];
+    return oa === ob ? 0 : oa < ob ? -1 : 1;
+}
+// This CLI's own version, read from its package.json (dist/.. at runtime).
+function cliVersion() {
+    try {
+        return JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(__dirname, '..', 'package.json'), 'utf8')).version;
+    }
+    catch {
+        return '0.0.0';
+    }
+}
+async function latestOnNpm(name) {
+    try {
+        const res = await fetch(`${REGISTRY}/${name.replace('/', '%2f')}/latest`);
+        if (!res.ok)
+            return null;
+        return (await res.json()).version ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+function installedVersion(name, projectDir) {
+    if (name === '@hypersoniclabs/helix-cli')
+        return cliVersion();
+    const candidates = [];
+    if (projectDir) {
+        candidates.push((0, node_path_1.join)(projectDir, 'node_modules', name, 'package.json'));
+    }
+    try {
+        candidates.push(require.resolve(`${name}/package.json`));
+    }
+    catch {
+        // not resolvable from here — fall through to the project-dir candidate
+    }
+    for (const p of candidates) {
+        try {
+            if ((0, node_fs_1.existsSync)(p)) {
+                return JSON.parse((0, node_fs_1.readFileSync)(p, 'utf8'))
+                    .version;
+            }
+        }
+        catch {
+            // unreadable / parse error — try the next candidate
+        }
+    }
+    return null;
+}
+// Compare each toolchain package's installed version against the latest on npm.
+// `installed` overrides let the running tool report its own version.
+// The exact command to bring a toolchain package to latest, in THIS build's scope.
+// Tools (cli/mcp) install by their real scoped name (npx / global). Libs (manifest/sdk)
+// are pinned in a project under the @hypersoniclabs import KEY: on prod that key IS the
+// package (direct install); on staging it must be an npm ALIAS to the @helixdev package so
+// the project's `@hypersoniclabs/*` import keeps resolving (matches the MCP's staging banner).
+function installHint(slot, scope) {
+    const importKey = `${IMPORT_SCOPE}/${slot}`;
+    const registryName = `${scope}/${slot}`;
+    if (isLib(slot)) {
+        return importKey === registryName
+            ? `npm i ${importKey}@latest`
+            : `npm i ${importKey}@npm:${registryName}@latest`;
+    }
+    return `run via "npx -y ${registryName}@latest" (always current), or update a global install: npm i -g ${registryName}@latest`;
+}
+async function checkForUpdates(opts = {}) {
+    const scope = opts.scope ?? config_1.HELIX_SCOPE;
+    return Promise.all(TOOLCHAIN_SLOTS.map(async (slot) => {
+        const importKey = `${IMPORT_SCOPE}/${slot}`;
+        const registryName = `${scope}/${slot}`;
+        const installed = opts.installed?.[importKey] ?? installedVersion(importKey, opts.projectDir);
+        const latest = await latestOnNpm(registryName);
+        const status = installed && latest
+            ? compareVersions(installed, latest) < 0
+                ? 'update-available'
+                : 'current'
+            : 'unknown';
+        const updateHint = installHint(slot, scope);
+        return { name: registryName, installed, latest, status, updateHint };
+    }));
+}
+//# sourceMappingURL=lib.js.map