@bitmagic/cli 0.1.18 → 0.1.20

package/dist/editor/journal.js

@@ -0,0 +1,214 @@
+/**
+ * The editor's event journal — how the agent that launched `bitmagic edit` finds out what the
+ * human did in the browser.
+ *
+ * For a drag, `git diff src/work/world.json` is already a complete record: the change is
+ * synchronous and self-describing. That stops being true the moment an editor action is
+ * asynchronous, costs money, or expresses an intention the editor cannot carry out itself — the
+ * "Generate high-quality version" button is all three. An agent watching only the file would see
+ * an asset mutate minutes later with no idea who asked, what it cost, or that anything is pending.
+ *
+ * So every editor action is appended here as one JSON object per line, and mirrored to stdout for
+ * whatever launched the command. The journal lives under `.bitmagic/`, which the scaffold
+ * gitignores: world.json is the tracked record of WHAT the scene is, and this is the untracked
+ * account of WHO changed it and WHY. Append-only and never rewritten, so an agent can read it
+ * incrementally (by byte offset or line count) without racing the writer.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+/** Journal location, relative to the project root. */
+export const JOURNAL_DIR = path.join('.bitmagic', 'edit');
+export const JOURNAL_FILE = 'events.jsonl';
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function asVec3(value) {
+    if (!isRecord(value))
+        return null;
+    const { x, y, z } = value;
+    if (typeof x !== 'number' || typeof y !== 'number' || typeof z !== 'number')
+        return null;
+    return { x, y, z };
+}
+/** A 1e-15 float wobble is not an edit worth a journal line. */
+function near(a, b) {
+    return Math.abs(a - b) < 1e-6;
+}
+/**
+ * Euler angles compare modulo a full turn.
+ *
+ * Not a nicety: world.json stores rotations in radians, and the engine hands back the value its
+ * own quaternion round-trip produced — so a `y` of 4.712 comes back as -1.571, the identical
+ * heading. Compared naively that is a rotation on every object the engine re-serializes, and the
+ * journal fills with turns nobody made.
+ */
+function sameAngle(a, b) {
+    const TWO_PI = Math.PI * 2;
+    const delta = Math.abs(a - b) % TWO_PI;
+    return near(delta, 0) || near(delta, TWO_PI);
+}
+function sameVec3(a, b, angular) {
+    if (a === null || b === null)
+        return a === b;
+    const same = angular ? sameAngle : near;
+    return same(a.x, b.x) && same(a.y, b.y) && same(a.z, b.z);
+}
+function transformDelta(before, after) {
+    const delta = {};
+    for (const field of ['position', 'rotation', 'scale']) {
+        const to = asVec3(after[field]);
+        if (to === null)
+            continue;
+        const from = before ? asVec3(before[field]) : null;
+        if (sameVec3(from, to, field === 'rotation'))
+            continue;
+        delta[field] = { from, to };
+    }
+    return delta;
+}
+function stringField(source, key) {
+    const value = source[key];
+    return typeof value === 'string' ? value : undefined;
+}
+/**
+ * What changed between the world on disk and what the engine is reporting.
+ *
+ * Pure, and given the BEFORE document rather than reading it — so the caller reads world.json once
+ * for both this and the modification builder, and the whole thing is testable without a filesystem
+ * or a browser.
+ *
+ * Silence is meaningful: an upserted object whose transform is unchanged produces no line. The
+ * engine re-serializes every object it was told is modified, including ones whose only "change"
+ * was being marked, and a journal that logged those would drown the real edits.
+ */
+export function deriveSceneEvents(before, payload) {
+    const previous = new Map();
+    for (const object of before.environmentObjects ?? []) {
+        const id = object.id;
+        if (typeof id === 'string')
+            previous.set(id, object);
+    }
+    const events = [];
+    for (const id of payload.changes.deletedObjectIds ?? []) {
+        const gone = previous.get(id);
+        events.push({
+            event: 'object.deleted',
+            objectId: id,
+            ...(gone ? { type: stringField(gone, 'type'), assetId: stringField(gone, 'assetId') } : {}),
+        });
+    }
+    const deleted = new Set(payload.changes.deletedObjectIds ?? []);
+    const fullSave = payload.changes.fullSaveNeeded === true;
+    const modified = new Set((payload.changes.modifiedObjectIds ?? []).filter((id) => id !== '__FULL_SAVE__' && !id.startsWith('spawn_')));
+    for (const object of payload.status.environmentObjects ?? []) {
+        const id = object.id;
+        if (typeof id !== 'string' || deleted.has(id))
+            continue;
+        if (!fullSave && !modified.has(id))
+            continue;
+        const was = previous.get(id);
+        if (was === undefined) {
+            events.push({
+                event: 'object.added',
+                objectId: id,
+                type: stringField(object, 'type'),
+                assetId: stringField(object, 'assetId'),
+                ...(asVec3(object.position) ? { position: asVec3(object.position) } : {}),
+            });
+            continue;
+        }
+        const delta = transformDelta(was, object);
+        if (Object.keys(delta).length === 0)
+            continue;
+        events.push({
+            event: 'object.moved',
+            objectId: id,
+            type: stringField(object, 'type'),
+            assetId: stringField(object, 'assetId'),
+            ...delta,
+        });
+    }
+    const spawnPoints = payload.changes.pendingSpawnPoints;
+    if (spawnPoints && spawnPoints.length > 0) {
+        const player = spawnPoints.find((point) => point.type === 'player');
+        const at = player ? asVec3(player.position) : null;
+        events.push({ event: 'spawn.changed', count: spawnPoints.length, ...(at ? { playerSpawn: at } : {}) });
+    }
+    if (payload.markersDirty === true) {
+        events.push({ event: 'markers.changed', count: (payload.status.markers ?? []).length });
+    }
+    const worldConfig = payload.changes.pendingWorldConfig;
+    if (worldConfig && Array.isArray(worldConfig.path) && worldConfig.path.length > 0) {
+        events.push({ event: 'worldconfig.changed', path: worldConfig.path });
+    }
+    return events;
+}
+function short(id) {
+    return id.length > 22 ? `${id.slice(0, 22)}…` : id;
+}
+function vec(value) {
+    if (value === null)
+        return '(new)';
+    const round = (n) => (Math.round(n * 100) / 100).toString();
+    return `(${round(value.x)}, ${round(value.y)}, ${round(value.z)})`;
+}
+/** The one-line human form mirrored to stdout. The JSONL line stays the machine contract. */
+export function formatEvent(event) {
+    switch (event.event) {
+        case 'session.started':
+            return `[edit] session.started ${event.gameId} → ${event.editorUrl}`;
+        case 'object.moved': {
+            const parts = ['position', 'rotation', 'scale']
+                .filter((field) => event[field] !== undefined)
+                .map((field) => `${field} ${vec(event[field].from)} → ${vec(event[field].to)}`);
+            return `[edit] object.moved ${short(event.objectId)}${event.type ? ` (${event.type})` : ''} ${parts.join(', ')}`;
+        }
+        case 'object.added':
+            return `[edit] object.added ${short(event.objectId)}${event.type ? ` (${event.type})` : ''} at ${vec(event.position ?? null)}`;
+        case 'object.deleted':
+            return `[edit] object.deleted ${short(event.objectId)}${event.type ? ` (${event.type})` : ''}`;
+        case 'spawn.changed':
+            return `[edit] spawn.changed ${event.count} spawn point(s)${event.playerSpawn ? `, player at ${vec(event.playerSpawn)}` : ''}`;
+        case 'markers.changed':
+            return `[edit] markers.changed ${event.count} marker(s)`;
+        case 'worldconfig.changed':
+            return `[edit] worldconfig.changed worldProfileData.${event.path.join('.')}`;
+        case 'hq.requested':
+            return `[edit] hq.requested "${event.assetName}" — run: ${event.command}`;
+    }
+}
+/**
+ * Append-only writer. Failures to write are reported through `log` and never thrown: the journal
+ * is a record OF the edit, and losing the record must not cost the creator the edit itself.
+ */
+export class EditorJournal {
+    file;
+    log;
+    now;
+    constructor(options) {
+        this.file = path.join(options.root, JOURNAL_DIR, JOURNAL_FILE);
+        this.log = options.log ?? (() => { });
+        this.now = options.now ?? (() => new Date().toISOString());
+    }
+    /** Absolute path of the journal, for the startup banner that tells an agent where to look. */
+    get path() {
+        return this.file;
+    }
+    append(...events) {
+        if (events.length === 0)
+            return;
+        const lines = events.map((event) => {
+            this.log(formatEvent(event));
+            return JSON.stringify({ at: this.now(), ...event });
+        });
+        try {
+            fs.mkdirSync(path.dirname(this.file), { recursive: true });
+            fs.appendFileSync(this.file, `${lines.join('\n')}\n`);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            this.log(`[edit] could not write ${this.file}: ${message}`);
+        }
+    }
+}
+//# sourceMappingURL=journal.js.map

package/dist/editor/journal.js.map

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

package/dist/editor/save.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Turn the game engine's own scene-editing replies into a `WorldJsonModification[]`.
+ *
+ * This is the CLI lane's counterpart to the Creator's `useSave.ts saveSceneModifications` and the
+ * spawn-point/world-config half of `useTabSwitching.ts deactivateScene`. The web lane posts its
+ * modifications to `POST /api/edit-world-config`, which rebuilds `predicateField`/`predicateValue`
+ * into real predicates server-side because functions cannot cross HTTP. Here there is no server:
+ * the shell page posts the engine's replies VERBATIM to the local sidecar, and this module — which
+ * runs in Node, in the same process that writes the file — builds the predicates directly.
+ *
+ * That split is deliberate. Everything that knows what world.json means lives on this side, so it
+ * is plain, synchronous, dependency-free code that can be unit-tested without a browser; the shell
+ * stays a dumb relay of `SCENE_HAS_CHANGES` and `SCENE_EDITING_STATUS`.
+ */
+import type { WorldJsonModification, WorldJsonShape } from '@bitmagic/world-forger/pipeline/index.js';
+/** The engine's `SCENE_HAS_CHANGES` reply (`CreatorMessageHandler.ts`, `CHECK_SCENE_CHANGES`). */
+export interface SceneChangeReport {
+    hasChanges?: boolean;
+    modifiedObjectIds?: string[];
+    deletedObjectIds?: string[];
+    fullSaveNeeded?: boolean;
+    pendingWorldConfig?: {
+        settings: unknown;
+        path: string[];
+        title?: string;
+    } | null;
+    pendingSpawnPoints?: Array<Record<string, unknown>> | null;
+}
+/** The engine's `SCENE_EDITING_STATUS` reply (`CreatorMessageHandler.ts`, line ~1463). */
+export interface SceneEditingStatus {
+    unlocked?: boolean;
+    environmentObjects?: Array<Record<string, unknown>>;
+    /**
+     * WHICH level `environmentObjects` covers. `serializeEnvironmentObjects()` walks the LIVE scene
+     * and a multi-level game only instantiates one level, so a non-null id means the array is this
+     * level plus untagged globals — never the whole world. `null` (single-level or legacy) means it
+     * genuinely is the whole world.
+     */
+    activeLevelId?: string | null;
+    markers?: Array<Record<string, unknown>>;
+}
+/** What the shell POSTs to `/api/scene/save`. Just the two engine replies, plus one flag. */
+export interface ScenePayload {
+    changes: SceneChangeReport;
+    status: SceneEditingStatus;
+    /** Set by the shell when the engine posted `ADD_MARKER` / `UPDATE_MARKER` since the last save. */
+    markersDirty?: boolean;
+}
+/**
+ * Build the write for one scene-editing flush. Returns `[]` when there is nothing to persist, so
+ * the caller can skip the file write entirely.
+ *
+ * `world` is the CURRENT parsed world.json, needed only to resolve the levels registry. Everything
+ * else comes from the engine, which is the source of truth for scene state — this never invents a
+ * position, rotation or scale.
+ */
+export declare function buildSceneModifications(payload: ScenePayload, world: WorldJsonShape): WorldJsonModification[];

package/dist/editor/save.js

@@ -0,0 +1,144 @@
+/**
+ * `EditorManager.markFullSaveNeeded()` pushes this sentinel into the same `Set` that holds real
+ * object ids, so it arrives in `modifiedObjectIds` and must be filtered out before any id is
+ * matched against an object. `fullSaveNeeded` carries the actual signal.
+ */
+const FULL_SAVE_SENTINEL = '__FULL_SAVE__';
+/** Spawn markers are tracked in the same modified-id set but persist through `pendingSpawnPoints`. */
+const SPAWN_ID_PREFIX = 'spawn_';
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** Match an array item by its `id`, the predicate every environmentObjects write uses. */
+function byId(id) {
+    return (item) => isRecord(item) && item.id === id;
+}
+/**
+ * The spawn-point half, mirroring `useTabSwitching.ts deactivateScene` lines 234-303.
+ *
+ * The rule that matters: in a levels game the spawns belong to the ACTIVE level's entry, and the
+ * flat `spawnPoints` / `playerSpawn*` fields are only mirrored when that level is the start level.
+ * Published games carry frozen template code that reads only the flat fields, so the mirror cannot
+ * be dropped — but writing it from a non-start level would make the wrong level's spawn the one
+ * every published build uses.
+ */
+function spawnPointModifications(spawnPoints, activeLevelId, world) {
+    const player = spawnPoints.find((point) => point.type === 'player');
+    const globals = [
+        { type: 'set', path: ['spawnPoints'], value: spawnPoints },
+    ];
+    if (player?.position !== undefined) {
+        globals.push({ type: 'set', path: ['playerSpawnPosition'], value: player.position });
+    }
+    // Only when present: writing `undefined` would drop the key on stringify for a game that had a
+    // rotation before, silently resetting the player's facing.
+    if (player?.rotationY !== undefined) {
+        globals.push({ type: 'set', path: ['playerSpawnRotationY'], value: player.rotationY });
+    }
+    const levels = world.worldProfileData?.levels ?? [];
+    if (levels.length === 0)
+        return globals;
+    const firstLevel = levels[0];
+    if (firstLevel === undefined)
+        return globals;
+    const startLevelId = world.worldProfileData?.startLevelId ?? firstLevel.id;
+    const targetId = activeLevelId ?? startLevelId;
+    const level = levels.find((entry) => entry.id === targetId);
+    // No matching entry means the engine reported a level this world.json does not know about.
+    // Falling back to the globals keeps the edit rather than dropping it on the floor.
+    if (level === undefined)
+        return globals;
+    const levelModification = {
+        type: 'update',
+        path: ['levels'],
+        predicate: (item) => isRecord(item) && item.id === level.id,
+        // An updater rather than a `{ ...level, spawnPoints }` snapshot (which is what the Creator
+        // builds): the snapshot was read before the write and would silently revert any other field
+        // the agent changed on this level in between.
+        value: (item) => ({ ...(isRecord(item) ? item : {}), spawnPoints }),
+    };
+    return level.id === startLevelId ? [levelModification, ...globals] : [levelModification];
+}
+/**
+ * Build the write for one scene-editing flush. Returns `[]` when there is nothing to persist, so
+ * the caller can skip the file write entirely.
+ *
+ * `world` is the CURRENT parsed world.json, needed only to resolve the levels registry. Everything
+ * else comes from the engine, which is the source of truth for scene state — this never invents a
+ * position, rotation or scale.
+ */
+export function buildSceneModifications(payload, world) {
+    const { changes, status } = payload;
+    const environmentObjects = status.environmentObjects ?? [];
+    const activeLevelId = status.activeLevelId ?? null;
+    const deletedObjectIds = changes.deletedObjectIds ?? [];
+    const modifiedObjectIds = (changes.modifiedObjectIds ?? []).filter((id) => id !== FULL_SAVE_SENTINEL && !id.startsWith(SPAWN_ID_PREFIX));
+    const modifications = [];
+    // Deletions first: order is the contract for `applyModificationsToWorld`, and an id that is both
+    // deleted and re-added in the same flush must end up added.
+    for (const id of deletedObjectIds) {
+        modifications.push({
+            type: 'removeRoot',
+            path: ['environmentObjects'],
+            predicate: byId(id),
+        });
+    }
+    if (changes.fullSaveNeeded === true) {
+        if (activeLevelId === null) {
+            // The array genuinely is the whole world, so replacing it wholesale is safe — and it is the
+            // only form that can DROP an object the engine no longer has but never reported deleting.
+            modifications.push({
+                type: 'setRoot',
+                path: ['environmentObjects'],
+                value: environmentObjects,
+            });
+        }
+        else {
+            // Deliberate divergence from the Creator, which issues a `setRoot` here. In a levels game the
+            // array holds only the active level plus globals, so a `setRoot` deletes every other level's
+            // scenery. Upserting each object writes exactly what the engine reported and touches nothing
+            // else.
+            for (const object of environmentObjects) {
+                const id = object.id;
+                if (typeof id !== 'string')
+                    continue;
+                modifications.push({
+                    type: 'upsertRoot',
+                    path: ['environmentObjects'],
+                    predicate: byId(id),
+                    value: object,
+                });
+            }
+        }
+    }
+    else {
+        const modifiedIds = new Set(modifiedObjectIds);
+        for (const object of environmentObjects) {
+            const id = object.id;
+            if (typeof id !== 'string' || !modifiedIds.has(id))
+                continue;
+            modifications.push({
+                type: 'upsertRoot',
+                path: ['environmentObjects'],
+                predicate: byId(id),
+                value: object,
+            });
+        }
+    }
+    if (changes.pendingWorldConfig) {
+        const { path, settings } = changes.pendingWorldConfig;
+        if (Array.isArray(path) && path.length > 0) {
+            modifications.push({ type: 'set', path, value: settings });
+        }
+    }
+    if (changes.pendingSpawnPoints && changes.pendingSpawnPoints.length > 0) {
+        modifications.push(...spawnPointModifications(changes.pendingSpawnPoints, activeLevelId, world));
+    }
+    if (payload.markersDirty === true) {
+        // Whole-array `set` rather than push/update: `SCENE_EDITING_STATUS` returns the live
+        // `markerSystem.serializeMarkers()` output, which already reflects adds, edits and removals.
+        modifications.push({ type: 'set', path: ['markers'], value: status.markers ?? [] });
+    }
+    return modifications;
+}
+//# sourceMappingURL=save.js.map

package/dist/editor/save.js.map

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

package/dist/editor/server.d.ts

@@ -0,0 +1,24 @@
+export interface EditorServerOptions {
+    /** The project root — the directory holding `bitmagic.json`. */
+    root: string;
+    /** The game this project owns, from `bitmagic.json`. */
+    gameId: string;
+    /** Port vite serves the game on; the shell iframes it. */
+    gamePort: number;
+    /** Port to bind. Fails loudly if taken — the URL is meant to be stable and bookmarkable. */
+    port: number;
+    log?: (message: string) => void;
+}
+export interface EditorServer {
+    /** The URL to open, e.g. `http://localhost:3011/`. */
+    readonly url: string;
+    /** Where editor actions are journalled, so the startup banner can point an agent at it. */
+    readonly journalPath: string;
+    close(): Promise<void>;
+}
+/**
+ * The command the agent should run to fulfil an HQ request. One definition, quoted for a shell,
+ * so the journal line, the HTTP reply and the editor's own confirmation cannot drift apart.
+ */
+export declare function hqCommand(assetId: string, prompt: string): string;
+export declare function startEditorServer(options: EditorServerOptions): Promise<EditorServer>;