@helix3/helix-cli 0.1.13-helix3.101 → 0.1.13-helix3.103

package/README.md

@@ -59,8 +59,69 @@ 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 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 world audit\|source-audit\|perf-gate\|prove-live` | Run the blocking world QA, performance, and deployed-build identity gates. |
+| `helix unreal init\|validate\|doctor\|package [project]` | Create and gate a shared-runtime or native-game publish manifest, check optional editor MCP, and assemble a local upload-shaped package. |
+| `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. |
 
+## Unreal runtime projects
+
+`helix unreal init <project> --mode shared-runtime|native-game` creates `helix.unreal.json`.
+Shared-runtime projects ship cooked content/Blueprints against a pinned HELIX runtime; native-game
+projects ship separate signed client/server builds and may use custom C++ and plugins. Both require
+Unreal 5.8, the HelixSDK plugin, and HelixPlatform identity/session integration.
+
+Networking is explicit: `unreal-native`, `helixnet`, `custom`, or `none`. Only `helixnet` requires
+contract v21; blank Unreal projects using arbitrary GameMode/Pawn classes and native networking do
+not need Lyra Experiences, Colyseus, or the HelixNet contract.
+
+`helix unreal validate` is the publish gate and does not require MCP. `helix unreal doctor` adds the
+loopback/editor-only Unreal MCP authoring checks. `helix unreal package` copies validated cooked or
+native artifacts into a local checksummed staging directory — it is a local assembly step, not a
+publish.
+
+### Publishing a cooked world
+
+`helix unreal publish <candidate> --world <slug-or-id>` takes the directory the Unreal
+`HelixWorldPublish` commandlet writes — `world-build-manifest.json`, its `.sha256` receipt,
+`cook-plan.json`, and `artifacts/<role>/…` — and gets it live in one command:
+
+```
+helix unreal publish Saved/HelixPublish --world my-world --max-players 32 --visibility unlisted
+```
+
+It verifies the candidate against the bytes on disk (every digest recomputed — a manifest is a
+claim, not evidence), registers the Build and presigns each artifact, streams the uploads,
+finalizes so the server re-verifies every byte by size and SHA-256 and countersigns the manifest,
+then promotes the Build as the world's active release. `--no-promote` stops after verification;
+`--verify-delivery` additionally checks what a client would actually download.
+
+The idempotency key defaults to the cooked manifest's own digest, so re-running after a dropped
+connection resumes the same Build rather than minting a second one.
+
+Only **shared-runtime** worlds publish this way. A World Build may not contain creator
+executables, so `native-game` builds are a separate distribution path.
+
+## Working in a git worktree? Run this first
+
+```
+npm run check:dev-links
+```
+
+`package.json` links its sibling HELIX packages by relative path
+(`file:../helix-manifest`, `file:../helix-web-sdk`). That is right in the canonical
+layout, where the siblings sit beside this clone — but in a **git worktree** `../` is
+the worktree parent, so the links resolve to whatever happens to be there: a checkout
+parked on an older branch, or nothing at all.
+
+The symptom is not "broken dev link". It is **a branch that looks broken**: `tsc`
+reporting `has no exported member …` in files your change never touched, and whole
+suites failing at import (`could not find the dev shell in @hypersoniclabs/helix-sdk`).
+People have concluded a PR was broken on the strength of exactly this.
+
+`check:dev-links` names which link is wrong, which imported symbols the linked sibling
+does not export, and how to fix it without repointing a shared directory other
+worktrees resolve through.
+
 ## Publish flow
 
 `helix publish` maps directly onto the backend's Instant World API:

package/dist/index.js

@@ -53,6 +53,8 @@ const config_1 = require("./config");
 const init_1 = require("./init");
 const prompt_1 = require("./prompt");
 const browserLogin_1 = require("./browserLogin");
+const unreal_1 = require("./unreal");
+const unrealPublish_1 = require("./unrealPublish");
 const program = new commander_1.Command();
 program
     .name('helix')
@@ -3171,6 +3173,150 @@ function formatWorldSystemRow(row) {
             return `? ${row.slug}: catalog query failed — currency unknown (${row.note.slice('catalog query failed ('.length, -1)})`;
     }
 }
+const unreal = program
+    .command('unreal')
+    .description('Prepare Unreal 5.8 projects for publishing to HELIX');
+function unrealArtifactMode(value) {
+    if (!unreal_1.UNREAL_ARTIFACT_MODES.includes(value)) {
+        fail(`✖ --mode must be one of: ${unreal_1.UNREAL_ARTIFACT_MODES.join(', ')}`);
+    }
+    return value;
+}
+function unrealNetworkingMode(value) {
+    if (!unreal_1.UNREAL_NETWORKING_MODES.includes(value)) {
+        fail(`✖ --networking must be one of: ${unreal_1.UNREAL_NETWORKING_MODES.join(', ')}`);
+    }
+    return value;
+}
+unreal
+    .command('init')
+    .description('Create the publish manifest for a shared-runtime or native-game project')
+    .argument('[project]', 'project directory', '.')
+    .requiredOption('--mode <mode>', 'shared-runtime or native-game')
+    .option('--networking <mode>', 'unreal-native, helixnet, custom, or none', 'none')
+    .option('--runtime-version <version>', 'pinned HELIX Unreal runtime version (shared-runtime only)')
+    .option('--force', `replace an existing helix.unreal.json`)
+    .option('--json', 'machine-readable result')
+    .action((project, opts) => {
+    try {
+        const result = (0, unreal_1.initUnrealManifest)(project, {
+            artifactMode: unrealArtifactMode(opts.mode),
+            networking: unrealNetworkingMode(opts.networking),
+            runtimeVersion: opts.runtimeVersion,
+            force: opts.force,
+        });
+        console.log(opts.json
+            ? JSON.stringify(result, null, 2)
+            : `✔ Created ${result.path}\n  mode: ${result.manifest.artifactMode}\n  networking: ${result.manifest.networking.mode}`);
+    }
+    catch (error) {
+        fail(`✖ ${error instanceof Error ? error.message : String(error)}`);
+    }
+});
+function registerUnrealValidationCommand(name, description) {
+    unreal
+        .command(name)
+        .description(description)
+        .argument('[project]', 'project directory or .uproject file', '.')
+        .option('--json', 'machine-readable validation report')
+        .action((project, opts) => {
+        const report = (0, unreal_1.validateUnrealProject)(project, { includeMcp: name === 'doctor' });
+        console.log(opts.json
+            ? JSON.stringify(report, null, 2)
+            : (0, unreal_1.formatUnrealValidationReport)(report));
+        if (!report.ok)
+            process.exitCode = 1;
+    });
+}
+registerUnrealValidationCommand('doctor', 'Check publish readiness plus safe editor-only Unreal MCP authoring setup');
+registerUnrealValidationCommand('validate', 'Validate the project and HELIX publish manifest without requiring editor MCP');
+unreal
+    .command('package')
+    .description('Assemble validated cooked/native artifacts into a local upload-shaped directory')
+    .argument('[project]', 'project directory', '.')
+    .option('--out <directory>', 'output directory (default: <project>/dist/helix-unreal-package)')
+    .option('--force', 'replace the exact output directory if it already exists')
+    .option('--json', 'machine-readable package result')
+    .action((project, opts) => {
+    const validation = (0, unreal_1.validateUnrealProject)(project);
+    if (!validation.ok) {
+        if (opts.json)
+            console.log(JSON.stringify({ validation, packaged: false }, null, 2));
+        else
+            console.log((0, unreal_1.formatUnrealValidationReport)(validation));
+        process.exitCode = 1;
+        return;
+    }
+    const output = opts.out ?? (0, node_path_1.resolve)(project, 'dist', 'helix-unreal-package');
+    const result = (0, unreal_1.packageUnrealProject)(project, output, { force: opts.force });
+    if (opts.json)
+        console.log(JSON.stringify(result, null, 2));
+    else if (result.ok) {
+        console.log(`✔ Prepared local HELIX package: ${result.outputDir}`);
+        console.log(`  ${result.index.files.length} files · ${result.index.totalBytes} bytes`);
+        console.log('  This is a local staging directory, not a publish. To publish a world, cook it with');
+        console.log('  the HelixWorldPublish commandlet and run: helix unreal publish <candidate> --world <slug>');
+    }
+    else {
+        console.log(`✖ ${result.errors.length} packaging problem(s):\n${result.errors.map((error) => `  - ${error}`).join('\n')}`);
+    }
+    if (!result.ok)
+        process.exitCode = 1;
+});
+unreal
+    .command('publish')
+    .description('Upload a cooked Unreal world to HELIX and promote it as the world’s active build')
+    .argument('[candidate]', 'the cook output directory containing world-build-manifest.json', '.')
+    .requiredOption('--world <slug-or-id>', 'the HELIX world to publish this build to')
+    .option('--max-players <count>', 'players per instance (1-1000)', '32')
+    .option('--activity <id>', 'activity id for the entry map', 'default')
+    .option('--idempotency-key <key>', 'override the key derived from the cooked manifest')
+    .option('--visibility <visibility>', 'private, unlisted, or public — sets the world’s catalog visibility on promote')
+    .option('--no-promote', 'upload and verify the build but leave the active release unchanged')
+    .option('--verify-delivery', 'after promoting, confirm what a client would download')
+    .option('--json', 'machine-readable result')
+    .action(async (candidate, opts) => {
+    const creds = requireAuth();
+    const maxPlayers = Number(opts.maxPlayers);
+    if (!Number.isInteger(maxPlayers) || maxPlayers < 1 || maxPlayers > 1000) {
+        fail('✖ --max-players must be a whole number between 1 and 1000');
+    }
+    if (opts.visibility && !['private', 'unlisted', 'public'].includes(opts.visibility)) {
+        fail('✖ --visibility must be private, unlisted, or public');
+    }
+    try {
+        const result = await (0, unrealPublish_1.publishUnrealBuild)(candidate, lib_1.HelixApi.forCredentials(creds), {
+            world: opts.world,
+            maxPlayers,
+            activityId: opts.activity,
+            idempotencyKey: opts.idempotencyKey,
+            promote: opts.promote,
+            visibility: opts.visibility,
+            engineVersion: unreal_1.HELIX_UNREAL_ENGINE_VERSION,
+            verifyDelivery: opts.verifyDelivery,
+        }, (message) => {
+            if (!opts.json)
+                console.log(`  ${message}`);
+        });
+        if (opts.json) {
+            console.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        console.log(result.promoted
+            ? `✔ Published build #${result.buildNumber} — it is now the active release for this world.`
+            : `✔ Verified build #${result.buildNumber}. It is not live: re-run without --no-promote to promote it.`);
+        console.log(`  build      ${result.buildId}`);
+        console.log(`  networking ${result.networkMode}`);
+        console.log(`  artifacts  ${result.artifactCount} · ${result.bundleSizeBytes.toLocaleString()} bytes${result.replayed ? ' (already uploaded — replayed)' : ''}`);
+        console.log(`  signed by  ${result.manifestSigningKeyId} over ${result.manifestDigest.slice(0, 16)}…`);
+        if (result.deliveryVerified) {
+            console.log('  delivery   verified against what a client would download');
+        }
+    }
+    catch (error) {
+        fail((0, unrealPublish_1.renderPublishFailure)(error));
+    }
+});
 program
     .command('doctor')
     .description('Health check: login state + whether the @helix toolchain (CLI/MCP/SDK/manifest) is up to date')