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

package/dist/unreal/avatarMode.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Avatar mode parsing and validation.
+ *
+ * This is a tiny, focused helper so the CLI option parser (index.ts) and the
+ * library function (release.ts) share the exact same validation and defaulting
+ * logic — and so it can be unit-tested in isolation.
+ */
+export type AvatarMode = 'universal' | 'world-default';
+/**
+ * Parse and validate an avatar mode value from CLI or config.
+ *
+ * - undefined / 'universal' -> 'universal' (the default, omitted from release)
+ * - 'world-default' -> 'world-default' (explicit opt-out)
+ * - anything else -> throws
+ */
+export declare function parseAvatarMode(value: string | undefined): AvatarMode;
+/**
+ * True when the mode should be emitted in the release document.
+ * Only 'world-default' is emitted; 'universal' is the implicit default.
+ */
+export declare function shouldEmitAvatarMode(mode: AvatarMode): boolean;

package/dist/unreal/avatarMode.js

@@ -0,0 +1,33 @@
+"use strict";
+/**
+ * Avatar mode parsing and validation.
+ *
+ * This is a tiny, focused helper so the CLI option parser (index.ts) and the
+ * library function (release.ts) share the exact same validation and defaulting
+ * logic — and so it can be unit-tested in isolation.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseAvatarMode = parseAvatarMode;
+exports.shouldEmitAvatarMode = shouldEmitAvatarMode;
+/**
+ * Parse and validate an avatar mode value from CLI or config.
+ *
+ * - undefined / 'universal' -> 'universal' (the default, omitted from release)
+ * - 'world-default' -> 'world-default' (explicit opt-out)
+ * - anything else -> throws
+ */
+function parseAvatarMode(value) {
+    const mode = value ?? 'universal';
+    if (mode !== 'universal' && mode !== 'world-default') {
+        throw new Error("avatarMode must be 'universal' or 'world-default'");
+    }
+    return mode;
+}
+/**
+ * True when the mode should be emitted in the release document.
+ * Only 'world-default' is emitted; 'universal' is the implicit default.
+ */
+function shouldEmitAvatarMode(mode) {
+    return mode === 'world-default';
+}
+//# sourceMappingURL=avatarMode.js.map

package/dist/unreal/avatarMode.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"avatarMode.js","sourceRoot":"","sources":["../../src/unreal/avatarMode.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG;;AAWH,0CAMC;AAMD,oDAEC;AArBD;;;;;;GAMG;AACH,SAAgB,eAAe,CAAC,KAAyB;IACvD,MAAM,IAAI,GAAG,KAAK,IAAI,WAAW,CAAC;IAClC,IAAI,IAAI,KAAK,WAAW,IAAI,IAAI,KAAK,eAAe,EAAE,CAAC;QACrD,MAAM,IAAI,KAAK,CAAC,mDAAmD,CAAC,CAAC;IACvE,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;GAGG;AACH,SAAgB,oBAAoB,CAAC,IAAgB;IACnD,OAAO,IAAI,KAAK,eAAe,CAAC;AAClC,CAAC"}

package/dist/unreal/delivery.d.ts

@@ -0,0 +1,46 @@
+import type { CliCredentials } from '../config';
+/**
+ * Fetches the signed client-delivery response for a published World build.
+ *
+ * WHY THIS EXISTS
+ *
+ * Launching a World is gated on a backend-signed delivery envelope: the desktop
+ * shell verifies its ES256 countersignature before a single byte is fetched, and
+ * the runtime refuses a launch whose command-line identity does not match it.
+ * That is the right design, and it meant the only way to run a published World
+ * was for a human to open the client and click. So every question that needs a
+ * running World -- does the shader library open, does a UMG widget appear, did a
+ * fix actually work -- was answerable only by asking someone to go and look.
+ *
+ * `HelixDesktop.WorldProbe` already drives the full production join path
+ * headlessly, and takes the delivery response as a file. It had no way to get
+ * one. This is that way.
+ */
+export type UnrealDeliveryOptions = {
+    worldId: string;
+    buildId: string;
+    outPath: string;
+    /**
+     * Write the whole HTTP response verbatim instead of the `item` payload.
+     *
+     * The default is the payload because that is what every consumer wants:
+     * `WorldBuildDeliveryVerifier.TryVerify` documents its input as "the raw
+     * `item` object from the client delivery response", and WorldProbe hands it
+     * the file contents unchanged. Writing the envelope by default would make the
+     * command's output fail verification for a reason that reads like a bad
+     * signature.
+     */
+    raw?: boolean;
+};
+export type UnrealDeliveryResult = {
+    worldId: string;
+    buildId: string;
+    outPath: string;
+    bytes: number;
+    /** Read from the response for reporting only; never used to alter the file. */
+    signingKeyId: string | null;
+    buildNumber: number | null;
+    networkMode: string | null;
+};
+export declare function deliveryPath(worldId: string, buildId: string): string;
+export declare function fetchUnrealDelivery(creds: CliCredentials, options: UnrealDeliveryOptions): Promise<UnrealDeliveryResult>;

package/dist/unreal/delivery.js

@@ -0,0 +1,89 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deliveryPath = deliveryPath;
+exports.fetchUnrealDelivery = fetchUnrealDelivery;
+const promises_1 = require("node:fs/promises");
+const node_path_1 = require("node:path");
+const api_1 = require("../api");
+/** `worlds/{id}/builds/{id}` — ids are path segments, so they are constrained. */
+const ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+function deliveryPath(worldId, buildId) {
+    return `/api/v1/worlds/${worldId}/builds/${buildId}/delivery/client`;
+}
+/**
+ * Reads a value out of the response for the summary line, tolerating a shape
+ * this code does not own.
+ *
+ * Deliberately separate from what gets WRITTEN: the file is the raw bytes, and
+ * nothing here may influence them.
+ */
+function peek(json) {
+    try {
+        const parsed = JSON.parse(json);
+        const build = (parsed.item ?? parsed.build ?? parsed);
+        const asString = (value) => (typeof value === 'string' ? value : null);
+        const asNumber = (value) => typeof value === 'number' && Number.isFinite(value) ? value : null;
+        return {
+            signingKeyId: asString(build.manifestSigningKeyId ?? parsed.signingKeyId ?? build.signingKeyId),
+            buildNumber: asNumber(build.buildNumber ?? build.manifest?.buildNumber),
+            networkMode: asString(build.networkMode ?? build.manifest?.networkMode),
+        };
+    }
+    catch {
+        // A response this code cannot parse is still a response WorldProbe may be
+        // able to verify -- the contract is the backend's, not this summary's.
+        return { signingKeyId: null, buildNumber: null, networkMode: null };
+    }
+}
+async function fetchUnrealDelivery(creds, options) {
+    const { worldId, buildId } = options;
+    if (!ID_PATTERN.test(worldId)) {
+        throw new Error(`Not a usable world id: ${JSON.stringify(worldId)}`);
+    }
+    if (!ID_PATTERN.test(buildId)) {
+        throw new Error(`Not a usable build id: ${JSON.stringify(buildId)}`);
+    }
+    const api = api_1.HelixApi.forCredentials(creds);
+    // requestBytes, NOT request<T>: this keeps the option of writing exactly what
+    // the backend sent, and keeps the raw text available for --raw.
+    const { bytes } = await api.requestBytes(deliveryPath(worldId, buildId));
+    const text = Buffer.from(bytes).toString('utf8');
+    // UNWRAPPING IS SAFE HERE, AND THAT IS A MEASURED CLAIM RATHER THAN A HOPE.
+    //
+    // The signature is not over these bytes. WorldBuildDelivery.cs canonicalises
+    // the `manifest` object (WorldBuildCanonicalJson.Canonicalize) and hashes THAT
+    // before checking the signature, so key order and whitespace in the transport
+    // JSON cannot affect verification. Re-serialising the payload is therefore
+    // lossless as far as the only thing that checks it is concerned.
+    //
+    // If that ever stops being true -- a signature taken over transport bytes --
+    // this must go back to writing `bytes` and WorldProbe must do the unwrapping.
+    let payload = text;
+    if (!options.raw) {
+        let parsed;
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch {
+            throw new Error('The delivery response is not JSON, so its payload cannot be extracted. ' +
+                'Re-run with --raw to write it unchanged and inspect it.');
+        }
+        const item = parsed?.item;
+        if (item === undefined) {
+            throw new Error('The delivery response carries no "item" payload. Re-run with --raw to write ' +
+                'the whole response unchanged.');
+        }
+        payload = JSON.stringify(item);
+    }
+    const outPath = (0, node_path_1.resolve)(options.outPath);
+    await (0, promises_1.mkdir)((0, node_path_1.dirname)(outPath), { recursive: true });
+    await (0, promises_1.writeFile)(outPath, payload, 'utf8');
+    return {
+        worldId,
+        buildId,
+        outPath,
+        bytes: Buffer.byteLength(payload),
+        ...peek(text),
+    };
+}
+//# sourceMappingURL=delivery.js.map

package/dist/unreal/delivery.js.map

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

package/dist/unreal/doctor.d.ts

@@ -0,0 +1,50 @@
+/**
+ * `helix unreal doctor` — the CLI face of the HELIX Unreal Project Doctor.
+ *
+ * One implementation, three surfaces (ADR-0001 applied to the Unreal lane):
+ * the Creator Kit panel, this CLI, and MCP all call the same
+ * `-run=HelixProjectDoctor` commandlet in the project's own engine install.
+ * This module owns none of the diagnosis logic — it locates the editor,
+ * drives the commandlet, and returns its machine-readable report verbatim.
+ *
+ * The commandlet's exit code is ordered by WHO MUST ACT and is part of its
+ * contract: 0 pass · 1 fixable · 2 creator action · 3 unsupported. Callers
+ * branch on `verdict`, never by parsing log text.
+ */
+export declare const DOCTOR_REPORT_SCHEMA = "helix.project-doctor-report/1";
+export type UnrealDoctorVerdict = 'pass' | 'fixable' | 'creator-action' | 'unsupported';
+export interface UnrealDoctorFinding {
+    checkId: string;
+    status: UnrealDoctorVerdict;
+    message: string;
+    fix?: string;
+}
+export interface UnrealDoctorReport {
+    schema: typeof DOCTOR_REPORT_SCHEMA;
+    projectDir: string;
+    verdict: UnrealDoctorVerdict;
+    findings: UnrealDoctorFinding[];
+}
+export interface UnrealDoctorResult {
+    report: UnrealDoctorReport;
+    /** The verdict's who-must-act ordinal (0..3), derived from the REPORT. */
+    exitCode: number;
+    uproject: string;
+    /** Set when the editor process exit disagreed with the report — measured on
+     *  real projects: the engine pollutes its exit code with error-logged asset
+     *  loads, so the report file is the only channel the engine cannot touch. */
+    processExitMismatch?: number;
+}
+/** How the editor is invoked; injectable so tests never need a real engine. */
+export interface UnrealEditorInvocation {
+    command: string;
+    prefixArgs: string[];
+}
+export declare function locateEditorCmd(ueRoot?: string | undefined): UnrealEditorInvocation;
+export declare function findUProject(projectDir: string): string;
+export declare function runUnrealDoctor(options: {
+    projectDir: string;
+    fix?: boolean;
+    editor?: UnrealEditorInvocation;
+    timeoutMs?: number;
+}): UnrealDoctorResult;

package/dist/unreal/doctor.js

@@ -0,0 +1,102 @@
+"use strict";
+/**
+ * `helix unreal doctor` — the CLI face of the HELIX Unreal Project Doctor.
+ *
+ * One implementation, three surfaces (ADR-0001 applied to the Unreal lane):
+ * the Creator Kit panel, this CLI, and MCP all call the same
+ * `-run=HelixProjectDoctor` commandlet in the project's own engine install.
+ * This module owns none of the diagnosis logic — it locates the editor,
+ * drives the commandlet, and returns its machine-readable report verbatim.
+ *
+ * The commandlet's exit code is ordered by WHO MUST ACT and is part of its
+ * contract: 0 pass · 1 fixable · 2 creator action · 3 unsupported. Callers
+ * branch on `verdict`, never by parsing log text.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DOCTOR_REPORT_SCHEMA = void 0;
+exports.locateEditorCmd = locateEditorCmd;
+exports.findUProject = findUProject;
+exports.runUnrealDoctor = runUnrealDoctor;
+const node_child_process_1 = require("node:child_process");
+const node_fs_1 = require("node:fs");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+exports.DOCTOR_REPORT_SCHEMA = 'helix.project-doctor-report/1';
+const VERDICT_BY_EXIT = {
+    0: 'pass',
+    1: 'fixable',
+    2: 'creator-action',
+    3: 'unsupported',
+};
+const ORDINAL_BY_VERDICT = {
+    pass: 0,
+    fixable: 1,
+    'creator-action': 2,
+    unsupported: 3,
+};
+function locateEditorCmd(ueRoot = process.env.UE_ROOT) {
+    if (!ueRoot) {
+        throw new Error('UE_ROOT is not set. Point it at an Unreal Engine 5.8 installation (the directory containing Engine/).');
+    }
+    const editor = (0, node_path_1.join)(ueRoot, 'Engine', 'Binaries', 'Win64', 'UnrealEditor-Cmd.exe');
+    if (!(0, node_fs_1.existsSync)(editor)) {
+        throw new Error(`UnrealEditor-Cmd.exe not found under UE_ROOT (${editor}).`);
+    }
+    return { command: editor, prefixArgs: [] };
+}
+function findUProject(projectDir) {
+    const dir = (0, node_path_1.resolve)(projectDir);
+    const projects = (0, node_fs_1.readdirSync)(dir).filter((name) => name.endsWith('.uproject'));
+    if (projects.length !== 1) {
+        throw new Error(`Expected exactly one .uproject in ${dir}, found ${projects.length}. Pass --project at the directory that holds it.`);
+    }
+    return (0, node_path_1.join)(dir, projects[0]);
+}
+function runUnrealDoctor(options) {
+    const editor = options.editor ?? locateEditorCmd();
+    const uproject = findUProject(options.projectDir);
+    const reportPath = (0, node_path_1.join)((0, node_fs_1.mkdtempSync)((0, node_path_1.join)((0, node_os_1.tmpdir)(), 'helix-doctor-')), 'doctor-report.json');
+    const args = [
+        ...editor.prefixArgs,
+        uproject,
+        '-run=HelixProjectDoctor',
+        ...(options.fix ? ['-Fix'] : []),
+        `-Report=${reportPath}`,
+        '-NullRHI',
+        '-unattended',
+        '-nosplash',
+    ];
+    const spawned = (0, node_child_process_1.spawnSync)(editor.command, args, {
+        // The editor's own log is the diagnostic of record; the CLI keeps stdio
+        // quiet and trusts the JSON report + exit code, the commandlet's contract.
+        stdio: 'ignore',
+        timeout: options.timeoutMs ?? 10 * 60 * 1000,
+    });
+    if (spawned.error) {
+        throw new Error(`Could not run the Unreal editor: ${spawned.error.message}`);
+    }
+    const processExit = spawned.status ?? -1;
+    if (!(0, node_fs_1.existsSync)(reportPath)) {
+        // A missing report is "the doctor did not run", never a verdict — the
+        // same absent-must-not-read-as-clean rule the repo's other gates follow.
+        throw new Error(`The Doctor produced no report (editor exit ${processExit}). The editor log names the cause; the report was expected at ${reportPath}.`);
+    }
+    const report = JSON.parse((0, node_fs_1.readFileSync)(reportPath, 'utf8'));
+    if (report.schema !== exports.DOCTOR_REPORT_SCHEMA) {
+        throw new Error(`Unexpected report schema "${report.schema}" (wanted ${exports.DOCTOR_REPORT_SCHEMA}).`);
+    }
+    const exitCode = ORDINAL_BY_VERDICT[report.verdict];
+    if (exitCode === undefined) {
+        throw new Error(`Report carries unknown verdict "${report.verdict}".`);
+    }
+    // The commandlet returns the same ordinal, but the ENGINE owns the process
+    // exit and pollutes it (error-logged asset loads on real projects exit 1
+    // under a passing report — measured on the Game Animation Sample). The
+    // report is authoritative; a mismatch is surfaced, never fatal.
+    const result = { report, exitCode, uproject };
+    if (VERDICT_BY_EXIT[processExit] !== report.verdict) {
+        result.processExitMismatch = processExit;
+    }
+    return result;
+}
+//# sourceMappingURL=doctor.js.map

package/dist/unreal/doctor.js.map

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

package/dist/unreal/package.d.ts

@@ -0,0 +1,80 @@
+import { type ContinuumPackage, type ContinuumPackageVersion } from '@hypersoniclabs/helix-manifest';
+import type { ContinuumPublicationIntent } from '../continuum/types';
+import type { WorldRelease } from '@hypersoniclabs/helix-manifest';
+/**
+ * Builds the Continuum Package and Package Version for a cooked Unreal World.
+ *
+ * Ported, not designed: the shape below is the one helix-manifest's own
+ * unreal-world.spec.ts builds, and everything is handed to their
+ * `validateContinuumPackageVersion` before it leaves this function.
+ *
+ * The cooked-role document is a real helix-manifest contract
+ * (`helix.continuum.unreal-cooked-role/1`): the descriptor's `roles[].manifest`
+ * pins the canonical-JSON CID and byte length of a document whose `files[]`
+ * entries are the cooked-file object references. There is deliberately no
+ * top-level `unrealWorld.objects[]` aggregate, so the exact closure is derived
+ * from those documents: `expectedClosure` must name every cooked byte the
+ * World owns or the backend seal (and the runtime capability grant) would omit
+ * it. The 1.86 GB UCAS is never read here; only the small role documents are.
+ */
+export type UnrealPackageOptions = {
+    publishDir: string;
+    packageId: string;
+    version: string;
+    name?: string;
+    /**
+     * Local file path for every object CID in the descriptor closure. When a
+     * cooked-role document's CID is present it is used to derive the exact
+     * cooked-file closure; otherwise the SDK layout
+     * `continuum/roles/<role>.json` under `publishDir` is used.
+     */
+    objectPaths?: Record<string, string>;
+};
+export type UnrealPackageResult = {
+    package: ContinuumPackage;
+    packageVersion: ContinuumPackageVersion;
+    /**
+     * Retained for compatibility. The cooked-role document is defined upstream
+     * now (`CONTINUUM_UNREAL_COOKED_ROLE_SCHEMA`), so this is always false.
+     */
+    roleObjectIsUndefinedUpstream: boolean;
+};
+export declare function buildUnrealPackageVersion(options: UnrealPackageOptions): Promise<UnrealPackageResult>;
+/**
+ * Assembles the Continuum publication intent for a cooked Unreal World.
+ *
+ * The point of this function is that it does NOT publish. `ContinuumPublisher`
+ * already owns the job -- objects, package, version, lease, seal, listings and
+ * the World Release -- with checkpointing and resume. Reimplementing any of it
+ * for Unreal would be the divergence this work exists to avoid, so the Unreal
+ * lane's whole contribution is producing a legal intent and handing it over.
+ *
+ * Every object is published from the ACTUAL file on disk: the canonical cooked
+ * role manifest documents and each per-file cooked object derived from each
+ * role document's `files[].object`. There is no `instant-world-adoption` here
+ * and no `unrealWorld.objects[]` aggregate. Role JSON is read under a strict
+ * small bound and must hash, byte for byte, to the CID the sealed descriptor
+ * pins; non-JSON cooked files are SHA-256 streamed so a 1.86 GB UCAS is never
+ * buffered. A mismatch fails closed rather than publishing bytes under an
+ * aggregate digest.
+ */
+export type UnrealIntentOptions = UnrealPackageOptions & {
+    projectId: string;
+    sourceDigest: string;
+    visibility?: 'private' | 'public';
+    world?: {
+        release: WorldRelease;
+        defaultRuntimeProfileId: string;
+    };
+    /**
+     * Local file path for every object CID in the descriptor closure: each
+     * `unrealWorld.roles[].manifest` cooked-role document AND every cooked file
+     * its `files[].object` references. The bytes are read and their CID is
+     * verified against the descriptor.
+     */
+    objectPaths: Record<string, string>;
+};
+export declare function buildUnrealPublicationIntent(options: UnrealIntentOptions): Promise<{
+    intent: ContinuumPublicationIntent;
+    roleObjectIsUndefinedUpstream: boolean;
+}>;