@bitmagic/cli 0.1.21 → 0.1.24

package/dist/editor/watch.js

@@ -0,0 +1,228 @@
+/**
+ * Deciding *when* the browser should reload.
+ *
+ * The hard part is not noticing a change — `fs.watch` does that — it is not reloading at the wrong
+ * moment. Three wrong moments, each of which this file exists to avoid:
+ *
+ *  1. **Mid-burst.** An agent editing five files produces five reloads unless the writes are let
+ *     go quiet first. Hence the debounce.
+ *  2. **Mid-compile.** A `.ts` edit changes `src/` long before `tsc --watch` finishes emitting
+ *     `dist/`, and every module the project loads resolves into `dist/`. Reloading on the source
+ *     write shows the creator the *old* build and reads as "my change did nothing". Hence the
+ *     compile gate: reloads are held while a compile is open and released when it lands clean.
+ *  3. **After a failed compile.** `dist/` still holds the last good emit, so a reload would show
+ *     working code for broken source — the most confusing outcome of the three. The pending reload
+ *     is dropped and the shell is told the build failed instead.
+ *
+ * `ReloadCoordinator` holds all of that and touches no I/O, so it is testable with fake timers and
+ * no filesystem. `watchProject` and `pipeTscWatch` are the thin I/O shells that feed it.
+ */
+import { spawn } from 'child_process';
+import * as fs from 'fs';
+import * as path from 'path';
+/**
+ * How long the writes must stay quiet before a reload fires.
+ *
+ * Long enough that `tsc --watch` (which has its own ~250 ms debounce before it reports
+ * `File change detected`) has almost always opened its compile by the time this elapses, so the
+ * gate below actually gets to hold the reload. Too short and a `.ts` edit produces two reloads —
+ * one stale, one correct — instead of one.
+ */
+export const RELOAD_QUIET_MS = 700;
+/**
+ * How long after one of our own writes to ignore file events.
+ *
+ * `/api/scene/save` and the HQ generation both write `world.json`, and a reload fired at the
+ * creator's own gizmo drag would throw away the drag that caused it. `fs.watch` delivers
+ * asynchronously but promptly, so this only has to outlast the delivery, not the write.
+ */
+export const OWN_WRITE_GRACE_MS = 400;
+export class ReloadCoordinator {
+    options;
+    timer = null;
+    pendingReason = null;
+    compiling = false;
+    suppressUntil = 0;
+    stopped = false;
+    constructor(options) {
+        this.options = { quietMs: RELOAD_QUIET_MS, ...options };
+    }
+    /** A file under a watched directory changed. Arms — or re-arms — the quiet window. */
+    noteFileChange(reason) {
+        if (this.stopped)
+            return;
+        if (Date.now() < this.suppressUntil)
+            return;
+        this.pendingReason = reason;
+        if (this.timer)
+            clearTimeout(this.timer);
+        this.timer = setTimeout(() => {
+            this.timer = null;
+            this.release();
+        }, this.options.quietMs);
+    }
+    /**
+     * Reload as soon as it is safe to — now, or the moment the compile in flight lands clean.
+     *
+     * The wait is the whole point for `bitmagic reload`: an agent's stop hook fires immediately after
+     * its last edit, which is precisely when `tsc` is still compiling it. Returns whether the reload
+     * was queued behind a compile rather than sent, so the command can say which happened.
+     */
+    requestNow(reason) {
+        if (this.stopped)
+            return { queued: false };
+        if (this.timer) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+        this.pendingReason = reason;
+        this.release();
+        return { queued: this.pendingReason !== null };
+    }
+    /** The sidecar wrote `world.json` itself; the resulting file events are not news. */
+    noteOwnWrite() {
+        this.suppressUntil = Date.now() + OWN_WRITE_GRACE_MS;
+    }
+    noteCompileStart() {
+        if (this.stopped || this.compiling)
+            return;
+        this.compiling = true;
+        this.options.onBuild('building');
+    }
+    noteCompileEnd(errorCount) {
+        if (this.stopped)
+            return;
+        this.compiling = false;
+        if (errorCount > 0) {
+            // Dropped, not deferred: `dist/` holds the last good emit, so reloading would show working
+            // code for broken source. The shell says so instead, and the next clean compile reloads.
+            this.pendingReason = null;
+            this.options.onBuild('failed', `${errorCount} TypeScript error${errorCount === 1 ? '' : 's'} — the game was not rebuilt.`);
+            return;
+        }
+        this.options.onBuild('ok');
+        this.release();
+    }
+    stop() {
+        this.stopped = true;
+        if (this.timer)
+            clearTimeout(this.timer);
+        this.timer = null;
+        this.pendingReason = null;
+    }
+    /** Send the pending reload, unless a compile is still open — then it waits for `noteCompileEnd`. */
+    release() {
+        if (this.pendingReason === null || this.compiling)
+            return;
+        const reason = this.pendingReason;
+        this.pendingReason = null;
+        this.options.onReload(reason);
+    }
+}
+/** Path segments that never mean "the project changed". */
+const IGNORED_SEGMENTS = new Set(['node_modules', '.bitmagic', '.vite-cache', '.git']);
+/**
+ * Editors write through temporary siblings — vim's `4913`/`~`, JetBrains' `___jb_tmp___`, an
+ * atomic-rename `.tmp`. Reloading on those means reloading on a file that no longer exists.
+ */
+function isIgnoredPath(relative) {
+    const segments = relative.split(path.sep);
+    if (segments.some((segment) => IGNORED_SEGMENTS.has(segment)))
+        return true;
+    const name = segments[segments.length - 1] ?? '';
+    return name.startsWith('.') || name.endsWith('~') || name.includes('___jb_') || name.endsWith('.tmp');
+}
+/**
+ * Watch the two directories that decide what the browser shows: `src/` (what the agent and the
+ * creator edit — including `work/world.json`) and `dist/` (what the page actually loads).
+ *
+ * `dist/` is watched as well as `src/` even though the compile gate already covers the normal
+ * `tsc --watch` path, because it is what a build run outside this process — a manual `tsc`, an
+ * editor's own compiler — lands in, and that should reach the browser too.
+ *
+ * A directory that cannot be watched is skipped with a note rather than failing the command: a
+ * missing `dist/` means "not built yet", and losing auto-reload is a smaller loss than losing
+ * `bitmagic dev`.
+ */
+export function watchProject(root, coordinator, log) {
+    const watchers = [];
+    for (const dir of ['src', 'dist']) {
+        const absolute = path.join(root, dir);
+        if (!fs.existsSync(absolute))
+            continue;
+        try {
+            const watcher = fs.watch(absolute, { recursive: true }, (_event, filename) => {
+                const relative = filename === null ? '' : String(filename);
+                if (relative !== '' && isIgnoredPath(relative))
+                    return;
+                coordinator.noteFileChange(path.posix.join(dir, relative.split(path.sep).join('/')));
+            });
+            watcher.on('error', (error) => {
+                log(`[dev] stopped watching ${dir}/: ${error.message}`);
+            });
+            watchers.push(watcher);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            log(`[dev] could not watch ${dir}/ (${message}) — reload on change is off for it.`);
+        }
+    }
+    return {
+        close: () => {
+            for (const watcher of watchers)
+                watcher.close();
+        },
+    };
+}
+/** tsc colourises when it thinks it is on a terminal; the markers below must match either way. */
+// eslint-disable-next-line no-control-regex
+const ANSI = /\u001B\[[0-9;]*m/g;
+const COMPILE_STARTED = /(File change detected|Starting compilation in watch mode)/;
+const COMPILE_FINISHED = /Found (\d+) error/;
+/**
+ * Feed one line of `tsc --watch` output to the coordinator. Exported for its test — the markers are
+ * tsc's own wording, and a version that changes them would otherwise break auto-reload silently.
+ */
+export function noteTscLine(line, coordinator) {
+    const plain = line.replace(ANSI, '');
+    const finished = COMPILE_FINISHED.exec(plain);
+    if (finished) {
+        coordinator.noteCompileEnd(Number(finished[1]));
+        return;
+    }
+    if (COMPILE_STARTED.test(plain))
+        coordinator.noteCompileStart();
+}
+/**
+ * Spawn `tsc --watch` with its output piped through us instead of inherited.
+ *
+ * Piping is what makes the compile gate possible — the only signal that a build finished, and
+ * whether it finished clean, is tsc's own `Found N errors` line. Every line is re-echoed verbatim,
+ * so the creator sees exactly what an inherited stdio would have shown, and `--pretty` is forced
+ * back on when our own stdout is a terminal (tsc drops colour the moment it is piped).
+ */
+export function pipeTscWatch(tsc, cwd, coordinator) {
+    const args = ['--watch', '--preserveWatchOutput'];
+    if (process.stdout.isTTY)
+        args.push('--pretty');
+    const child = spawn(tsc, args, { cwd, stdio: ['inherit', 'pipe', 'pipe'] });
+    const consume = (stream, echo) => {
+        if (!stream)
+            return;
+        let buffered = '';
+        stream.setEncoding('utf-8');
+        stream.on('data', (chunk) => {
+            echo.write(chunk);
+            buffered += chunk;
+            const lines = buffered.split('\n');
+            // The last element is whatever came after the final newline — an incomplete line, held over.
+            buffered = lines.pop() ?? '';
+            for (const line of lines)
+                noteTscLine(line, coordinator);
+        });
+    };
+    consume(child.stdout, process.stdout);
+    consume(child.stderr, process.stderr);
+    return child;
+}
+//# sourceMappingURL=watch.js.map

package/dist/editor/watch.js.map

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

package/dist/generate/stream.d.ts

@@ -6,11 +6,24 @@ export interface GenerationOutcome {
     message: string;
     patches: WorldPatch[];
     /**
-     * Only the `prop` type sets this. That generator produces a mesh rather than a finished asset —
-     * the caller voxelizes it in a browser before there is anything to write — so for `prop` this,
-     * not `patches`, is the result that matters. Absent for every other type.
+     * Only the `prop` and `vehicle` types set this. Those generators produce a mesh rather than a
+     * finished asset — the caller voxelizes it in a browser before there is anything to write — so
+     * for them this, not `patches`, is the result that matters. Absent for every other type.
      */
     glbUrl?: string;
+    /**
+     * Only the `vehicle` type sets this: the bake settings its GLB was authored for. `minVoxelSize`
+     * is derived from the vehicle's own proportions rather than fixed, so the CLI cannot pick it —
+     * it has to come back from the server with the mesh.
+     */
+    vehicle?: VehicleOutcome;
+}
+export interface VehicleOutcome {
+    name: string;
+    minVoxelSize: number;
+    maxVoxelSize: number;
+    /** Cosmetic repairs and dropped wrap layers — worth showing, never failures. */
+    notes: string[];
 }
 export interface StreamDeps {
     fetch: typeof globalThis.fetch;

package/dist/generate/stream.js

@@ -15,18 +15,39 @@ function asProgressMessage(data) {
  * `WorldPatch[]` contract is re-validated field-by-field later by
  * `apply-patches.ts`'s `validateWorldPatch` before anything is written to disk.
  */
+/**
+ * Structural, like the rest of this parser: a frame carrying a malformed `vehicle` is treated as
+ * carrying none, so a server that ever changed the shape degrades into "no bake settings" (a clear
+ * failure at the voxelize step) rather than into a NaN voxel size.
+ */
+function asVehicleOutcome(value) {
+    if (!isRecord(value))
+        return null;
+    const { name, minVoxelSize, maxVoxelSize, notes } = value;
+    if (typeof name !== 'string' || typeof minVoxelSize !== 'number' || typeof maxVoxelSize !== 'number') {
+        return null;
+    }
+    return {
+        name,
+        minVoxelSize,
+        maxVoxelSize,
+        notes: Array.isArray(notes) ? notes.filter((n) => typeof n === 'string') : [],
+    };
+}
 function asGenerationOutcome(data) {
     if (!isRecord(data))
         return null;
-    const { success, message, patches, glbUrl } = data;
+    const { success, message, patches, glbUrl, vehicle } = data;
     if (typeof success !== 'boolean' || typeof message !== 'string' || !Array.isArray(patches)) {
         return null;
     }
+    const vehicleOutcome = asVehicleOutcome(vehicle);
     return {
         success,
         message,
         patches: patches,
         ...(typeof glbUrl === 'string' ? { glbUrl } : {}),
+        ...(vehicleOutcome ? { vehicle: vehicleOutcome } : {}),
     };
 }
 async function readJsonBody(response) {

package/dist/generate/stream.js.map

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

package/dist/generate/vehicle.d.ts

@@ -0,0 +1,53 @@
+import type { Environment } from '../config/environments.js';
+import type { ProjectContext } from '../project/context.js';
+export interface VehicleVoxelizeOptions {
+    context: ProjectContext;
+    environment: Environment;
+    token: string;
+    /** Asset name — the name game code spawns by. */
+    name: string;
+    glbUrl: string;
+    minVoxelSize: number;
+    maxVoxelSize: number;
+    /** What the vehicle was asked for, used as the asset description when the GLB carries none. */
+    description: string;
+    log: (message: string) => void;
+}
+export interface GenerateAndInstallVehicleOptions {
+    context: ProjectContext;
+    environment: Environment;
+    token: string;
+    prompt?: string;
+    presetName?: string;
+    name?: string;
+    /** Skip the paid design and voxelize this GLB instead — how a failed run is retried. */
+    glbUrl?: string;
+    /** Required alongside `glbUrl`: the bake resolution is not recoverable from the other flags. */
+    minVoxelSize?: number;
+    fetchImpl?: typeof globalThis.fetch;
+    log: (message: string) => void;
+}
+export interface VehicleInstallResult {
+    assetId: string;
+    assetName: string;
+    assetUrl?: string;
+    /**
+     * False when the engine registered the asset without physics fitment — it will not drive. Not an
+     * error: the asset is real and placeable, so this is reported rather than thrown.
+     */
+    drivable: boolean;
+    /** Cosmetic repairs and dropped wrap layers from the build. */
+    notes: string[];
+}
+/**
+ * Steps 1-3. Everything the caller must resolve first (project, environment, token) is a parameter,
+ * so this stays free of CLI output plumbing and of how the token was obtained.
+ */
+export declare function generateAndInstallVehicle(options: GenerateAndInstallVehicleOptions): Promise<VehicleInstallResult & {
+    glbUrl: string;
+}>;
+/**
+ * Steps 2 and 3. Split from the command so the browser work is callable directly on a retry that
+ * already has a GLB, and so the command file stays about flags and output.
+ */
+export declare function voxelizeAndInstallVehicle(options: VehicleVoxelizeOptions): Promise<VehicleInstallResult>;

package/dist/generate/vehicle.js

@@ -0,0 +1,227 @@
+/**
+ * `bitmagic generate vehicle` — design a drivable vehicle and register it as an asset.
+ *
+ * Three steps, the same shape `generate prop` uses:
+ *
+ *   1. Ask api-server to design + build the vehicle (`POST /api/cli/v1/assets/vehicle/stream`).
+ *      The designer LLM and the Asset Forger credentials live there and never reach this machine.
+ *   2. Voxelize the GLB in a browser. Only the engine can do this, so the CLI drives its own
+ *      headless Chrome — the same arrangement `bitmagic forge` and `generate prop` use.
+ *   3. Upsert the finished asset into `assets[]`.
+ *
+ * Where this deliberately differs from `prop`, which upgrades an EXISTING asset in place:
+ *
+ *   - No asset is looked up first, and none is required. A vehicle is a NEW asset; requiring a
+ *     placeholder to already exist would make the command unusable.
+ *   - No `fitBox` and no `assetId` are sent. The engine derives the vehicle's physics fitment from
+ *     the GLB's own `bmVehicle` scene extras and mints the id. Passing a fitBox would rescale the
+ *     body off its authored ride stance and silently produce wrong physics.
+ *   - The bake resolution comes from the server frame, not a constant: it is derived from the
+ *     vehicle's own proportions (a semi tractor and a go-kart do not bake at the same voxel size).
+ *
+ * The GLB survives a failure in steps 2-3: it is reported in the error so a retry can be pointed at
+ * it with `--glb-url` rather than paying for the design twice.
+ */
+import { spawn } from 'child_process';
+import { CliError } from '../errors.js';
+import { applyModificationsToWorld } from '../forge/apply-modifications.js';
+import { ForgeBrowserHost, readProjectGameData } from '../forge/browser-host.js';
+import { projectWorldJsonPath } from '../forge/run-pipeline.js';
+import { startUploadProxy } from '../forge/upload-proxy.js';
+import { requestGeneration } from './stream.js';
+import { reserveCorsAllowedPort } from '../local-port.js';
+import { projectBin } from '../project/context.js';
+import { waitForServer } from '../verify/wait-for-server.js';
+/** Voxelizing a dense mesh is minutes of work in the browser, not seconds. */
+const VOXELIZE_TIMEOUT_MS = 10 * 60 * 1000;
+/**
+ * A vehicle body is a closed shell around a cabin; baked hollow it reads as a shell the moment the
+ * camera clips inside, and every preset is well under the size where a solid fill gets expensive.
+ * Matches what the agent lane's vehicle pipeline has always passed.
+ */
+const FILL_INTERIOR = true;
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * Steps 1-3. Everything the caller must resolve first (project, environment, token) is a parameter,
+ * so this stays free of CLI output plumbing and of how the token was obtained.
+ */
+export async function generateAndInstallVehicle(options) {
+    const { context, environment, token, prompt, presetName, name, log } = options;
+    if (options.glbUrl !== undefined) {
+        if (options.minVoxelSize === undefined) {
+            throw new CliError('--glb-url needs --voxel-size too: the bake resolution is derived from the vehicle\'s own '
+                + 'proportions during the design step, so it cannot be recovered from the other flags. '
+                + 'The failed run printed the exact command to retry with.');
+        }
+        if (name === undefined) {
+            throw new CliError('--glb-url needs --name too, so the asset can be registered under the right name.');
+        }
+        log(`Reusing the vehicle at ${options.glbUrl} — skipping the design step.`);
+        const result = await voxelizeAndInstallVehicle({
+            context,
+            environment,
+            token,
+            name,
+            glbUrl: options.glbUrl,
+            minVoxelSize: options.minVoxelSize,
+            // Unlike minVoxelSize this is a fixed LOD ceiling, so a retry can restate it.
+            maxVoxelSize: 0.5,
+            description: prompt ?? presetName ?? name,
+            log,
+        });
+        return { ...result, glbUrl: options.glbUrl };
+    }
+    const outcome = await requestGeneration(environment, token, 'vehicle', {
+        gameId: context.metadata.gameId,
+        ...(prompt !== undefined ? { prompt } : {}),
+        ...(presetName !== undefined ? { presetName } : {}),
+        ...(name !== undefined ? { name } : {}),
+    }, { fetch: options.fetchImpl ?? globalThis.fetch, onProgress: log });
+    if (!outcome.success)
+        throw new CliError(`${outcome.message} world.json is unchanged.`);
+    if (!outcome.glbUrl || !outcome.vehicle) {
+        throw new CliError('The generator reported success but returned no vehicle mesh. world.json is unchanged.');
+    }
+    const glbUrl = outcome.glbUrl;
+    const { vehicle } = outcome;
+    log(`Vehicle built: ${glbUrl}`);
+    for (const note of vehicle.notes)
+        log(`  note: ${note}`);
+    const result = await voxelizeAndInstallVehicle({
+        context,
+        environment,
+        token,
+        name: vehicle.name,
+        glbUrl,
+        minVoxelSize: vehicle.minVoxelSize,
+        maxVoxelSize: vehicle.maxVoxelSize,
+        description: prompt ?? presetName ?? vehicle.name,
+        log,
+    });
+    return { ...result, glbUrl, notes: [...vehicle.notes, ...result.notes] };
+}
+/** How a failed voxelize tells the caller to retry without paying for the design again. */
+function retryHint(name, glbUrl, minVoxelSize) {
+    return `The vehicle mesh is kept — retry the browser step with:\n`
+        + `  bitmagic generate vehicle --glb-url ${glbUrl} --voxel-size ${minVoxelSize} --name "${name}"`;
+}
+/**
+ * Steps 2 and 3. Split from the command so the browser work is callable directly on a retry that
+ * already has a GLB, and so the command file stays about flags and output.
+ */
+export async function voxelizeAndInstallVehicle(options) {
+    const { context, environment, token, name, glbUrl, minVoxelSize, maxVoxelSize, description, log } = options;
+    const worldPath = projectWorldJsonPath(context.root);
+    const port = await reserveCorsAllowedPort();
+    if (port === null) {
+        throw new CliError('No free port between 3000 and 3199, which is the only range the asset CDN serves. '
+            + `Stop something in that range and retry.\n${retryHint(name, glbUrl, minVoxelSize)}`);
+    }
+    const vite = projectBin(context.root, 'vite');
+    let server;
+    let host;
+    let uploadProxy;
+    try {
+        server = spawn(vite, ['--port', String(port), '--strictPort'], {
+            cwd: context.root,
+            stdio: ['ignore', 'ignore', 'pipe'],
+        });
+        let viteStderr = '';
+        server.stderr?.on('data', (chunk) => { viteStderr += String(chunk); });
+        try {
+            await waitForServer(port, 30_000);
+        }
+        catch {
+            throw new CliError(`The project's dev server did not come up on port ${port}, so the vehicle cannot be voxelized.`
+                + (viteStderr.trim() ? `\n${viteStderr.trim()}` : '')
+                + `\n${retryHint(name, glbUrl, minVoxelSize)}`);
+        }
+        // The engine uploads the baked .vxl itself, to a presigned URL it asks for at a hardcoded
+        // path with no credentials. The proxy translates that into the authenticated api-server route
+        // and keeps the token out of the page — see forge/upload-proxy.ts.
+        uploadProxy = await startUploadProxy({
+            apiUrl: environment.apiUrl,
+            token,
+            gameId: context.metadata.gameId,
+            log,
+        });
+        host = new ForgeBrowserHost({
+            gamePort: port,
+            gameId: context.metadata.gameId,
+            gameData: readProjectGameData(context.root, context.metadata),
+            agentUrl: uploadProxy.url,
+            log,
+        });
+        await host.launch();
+        await host.loadGame();
+        log(`Voxelizing "${name}" at ${minVoxelSize}m…`);
+        const result = await host.transport.sendAndWait({
+            type: 'CREATE_ASSET_FROM_GLB_URL',
+            requestId: `vehicle-${port}`,
+            name,
+            glbUrl,
+            // No `assetId`: the engine mints one, and no `fitBox`: fitment comes from the GLB's own
+            // bmVehicle extras. See this file's header for why both matter.
+            options: {
+                minVoxelSize,
+                maxVoxelSize,
+                fillInterior: FILL_INTERIOR,
+                placeholder: false,
+            },
+        }, 'ASSET_FROM_GLB_URL_RESULT', VOXELIZE_TIMEOUT_MS, { maxRetries: 1 });
+        if (!result) {
+            throw new CliError(`Voxelizing "${name}" timed out.\n${retryHint(name, glbUrl, minVoxelSize)}`);
+        }
+        if (result.success === false || !isRecord(result.asset)) {
+            const reason = typeof result.error === 'string' ? result.error : 'unknown error';
+            throw new CliError(`Voxelizing "${name}" failed: ${reason}.\n${retryHint(name, glbUrl, minVoxelSize)}`);
+        }
+        const engineAsset = result.asset;
+        const assetId = typeof engineAsset.id === 'string' ? engineAsset.id : '';
+        if (assetId === '') {
+            throw new CliError(`The engine registered "${name}" but returned no asset id, so it cannot be written to `
+                + `world.json.\n${retryHint(name, glbUrl, minVoxelSize)}`);
+        }
+        const asset = {
+            ...engineAsset,
+            description: typeof engineAsset.description === 'string' && engineAsset.description.trim() !== ''
+                ? engineAsset.description
+                : description,
+        };
+        const modification = {
+            type: 'upsertRoot',
+            path: ['assets'],
+            predicate: (item) => isRecord(item) && item.id === assetId,
+            value: asset,
+        };
+        applyModificationsToWorld(worldPath, [modification]);
+        // No fitment means the asset registered but will not drive. Reported rather than thrown: the
+        // asset is real, and the usual cause is a project whose vendored engine predates fitment
+        // derivation — which `bitmagic upgrade` fixes without regenerating anything.
+        const drivable = isRecord(engineAsset.vehicleFitment);
+        const notes = drivable
+            ? []
+            : ['The engine returned no vehicleFitment, so this asset will not drive. '
+                    + 'Run `bitmagic upgrade` to update the project\'s vendored engine, then regenerate.'];
+        return {
+            assetId,
+            assetName: name,
+            ...(typeof asset.url === 'string' ? { assetUrl: asset.url } : {}),
+            drivable,
+            notes,
+        };
+    }
+    finally {
+        // Ordered: the page first (it may still be mid-upload), then the proxy it was uploading
+        // through, then the server underneath both.
+        if (host)
+            await host.close();
+        if (uploadProxy)
+            await uploadProxy.close();
+        if (server)
+            server.kill('SIGTERM');
+    }
+}
+//# sourceMappingURL=vehicle.js.map

package/dist/generate/vehicle.js.map

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

package/dist/local-port.d.ts

@@ -16,6 +16,16 @@
  */
 export declare const CORS_ALLOWED_PORT_MIN = 3000;
 export declare const CORS_ALLOWED_PORT_MAX = 3199;
+/**
+ * A `--port`-style flag parsed and checked against the window above.
+ *
+ * Every port `bitmagic dev` binds goes through here, the game port for the reason documented above
+ * and the shell port because the two are adjacent by default: a creator who moves one will move the
+ * other, and being told the rule once, at the point of the mistake, beats discovering it as a
+ * terrain-less world. (The shell itself fetches nothing from the CDN, so its own check is purely
+ * that kindness.)
+ */
+export declare function parseLocalPort(value: string | undefined, fallback: number, flag: string): number;
 /**
  * A free port the CDN will serve assets to, or `null` when the whole window is taken.
  *