@waica/cli 0.4.2 → 0.6.0

package/dist/mcp/runtime-session-manager.js

@@ -0,0 +1,265 @@
+import { realpath } from 'node:fs/promises';
+import path from 'node:path';
+import { startRuntimeBrowser } from './runtime-browser.js';
+import { startRuntimeDevServer } from './runtime-dev-server.js';
+import { preflightRuntimeProject, } from './runtime-preflight.js';
+import { RuntimeToolError, } from './runtime-service.js';
+function message(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+export class RuntimeSessionManager {
+    adapters;
+    sessions = new Map();
+    starts = new Map();
+    closing = false;
+    constructor(adapters) {
+        this.adapters = adapters;
+    }
+    async start(input) {
+        if (this.closing) {
+            throw new RuntimeToolError({
+                code: 'runtime-invalid-state',
+                stage: 'cleanup',
+                message: 'The MCP server is closing and cannot start another Run Session.',
+                projectPath: input.projectPath,
+            });
+        }
+        const canonical = await this.adapters.canonicalize(input.projectPath);
+        const current = this.sessions.get(canonical);
+        if (current) {
+            if (current.state !== 'active') {
+                throw new RuntimeToolError({
+                    code: 'runtime-invalid-state',
+                    stage: 'game',
+                    message: `The Run Session is ${current.state}; retry after it is active.`,
+                    projectPath: canonical,
+                });
+            }
+            return this.startResult(current, true);
+        }
+        const concurrent = this.starts.get(canonical);
+        if (concurrent)
+            return this.startResult(await concurrent, true);
+        const creation = this.createCheckedSession({ ...input, projectPath: canonical });
+        this.starts.set(canonical, creation);
+        try {
+            const session = await creation;
+            this.sessions.set(canonical, session);
+            return this.startResult(session, false);
+        }
+        finally {
+            this.starts.delete(canonical);
+        }
+    }
+    async stop(projectPath) {
+        const canonical = await this.adapters.canonicalize(projectPath);
+        const starting = this.starts.get(canonical);
+        if (starting)
+            await starting.catch(() => { });
+        const session = this.sessions.get(canonical);
+        if (!session)
+            return { projectPath: canonical, stopped: false };
+        try {
+            await this.cleanupSession(session);
+        }
+        finally {
+            this.sessions.delete(canonical);
+        }
+        return { projectPath: canonical, stopped: true };
+    }
+    async inspect(input) {
+        const session = await this.requireSession(input.projectPath);
+        const inspected = await session.browser.inspect({
+            ...(input.entityIds ? { entityIds: input.entityIds } : {}),
+            ...(input.entityNames ? { entityNames: input.entityNames } : {}),
+            ...(input.componentTypes ? { componentTypes: input.componentTypes } : {}),
+        });
+        return {
+            ...this.sharedMetadata(session, inspected),
+            snapshot: inspected.snapshot ?? inspected,
+        };
+    }
+    async control(input) {
+        const session = await this.requireSession(input.projectPath);
+        const { projectPath: _projectPath, ...request } = input;
+        const controlled = await session.browser.control(request);
+        return { ...this.sharedMetadata(session, controlled), heldActions: controlled.heldActions ?? [] };
+    }
+    async captureScreenshot(projectPath) {
+        const session = await this.requireSession(projectPath);
+        const screenshot = await session.browser.captureScreenshot();
+        const { data, ...metadata } = screenshot;
+        return { metadata: this.sharedMetadata(session, metadata), data };
+    }
+    async close() {
+        if (this.closing)
+            return;
+        this.closing = true;
+        await Promise.allSettled([...this.starts.values()]);
+        const sessions = [...this.sessions.values()];
+        const results = await Promise.allSettled(sessions.map((session) => this.cleanupSession(session)));
+        this.sessions.clear();
+        const failed = results.find((result) => result.status === 'rejected');
+        if (failed)
+            throw failed.reason;
+    }
+    async createCheckedSession(input) {
+        const preflight = await this.adapters.preflight(input);
+        return this.createSession(preflight);
+    }
+    async createSession(preflight) {
+        let devServer;
+        let browser;
+        try {
+            devServer = await this.adapters.startDevServer(preflight);
+            browser = await this.adapters.startBrowser(preflight, devServer);
+            const ready = await browser.ready();
+            if (ready.bridgeVersion !== 1) {
+                throw new RuntimeToolError({
+                    code: 'runtime-incompatible',
+                    stage: 'bridge',
+                    message: `The Project engine does not provide Runtime Bridge protocol 1; upgrade @waica/engine to at least ${preflight.engine.version}.`,
+                    projectPath: preflight.projectPath,
+                    diagnostics: { minimumEngineVersion: preflight.engine.version },
+                });
+            }
+            const session = {
+                preflight,
+                devServer,
+                browser,
+                state: 'active',
+                ready,
+            };
+            devServer.setExitHandler?.((detail) => {
+                void this.failSession(session, new Error(`Project dev process exited: ${JSON.stringify(detail)}`));
+            });
+            browser.setLifecycleHandlers({
+                reloading: () => {
+                    if (session.state === 'active')
+                        session.state = 'reloading';
+                },
+                reloaded: (nextReady) => {
+                    if (session.state !== 'stopped') {
+                        session.ready = nextReady;
+                        session.state = 'active';
+                    }
+                },
+                failed: (error) => {
+                    void this.failSession(session, error);
+                },
+            });
+            return session;
+        }
+        catch (error) {
+            await browser?.close().catch(() => { });
+            await devServer?.stop().catch(() => { });
+            if (error instanceof RuntimeToolError)
+                throw error;
+            throw new RuntimeToolError({
+                code: 'runtime-start-failed',
+                stage: browser ? 'bridge' : devServer ? 'browser' : 'dev-server',
+                message: message(error),
+                projectPath: preflight.projectPath,
+                diagnostics: devServer?.diagnostics(),
+            });
+        }
+    }
+    async startResult(session, reused) {
+        const { preflight, devServer, ready } = session;
+        const current = reused ? await session.browser.inspect({}) : ready;
+        return {
+            projectPath: preflight.projectPath,
+            url: devServer.url,
+            reused,
+            viewport: preflight.viewport,
+            engineVersion: String(current.engineVersion ?? ready.engineVersion),
+            bridgeVersion: Number(current.bridgeVersion ?? ready.bridgeVersion),
+            mode: (current.mode ?? ready.mode),
+            frame: Number(current.frame ?? ready.frame),
+            simulationTime: Number(current.simulationTime ?? ready.simulationTime),
+            provenance: [preflight.engine],
+            initialSnapshot: ready.initialSnapshot,
+        };
+    }
+    sharedMetadata(session, value) {
+        return {
+            projectPath: session.preflight.projectPath,
+            url: session.devServer.url,
+            engineVersion: value.engineVersion ?? session.ready.engineVersion,
+            bridgeVersion: value.bridgeVersion ?? session.ready.bridgeVersion,
+            mode: value.mode ?? session.ready.mode,
+            frame: value.frame ?? session.ready.frame,
+            simulationTime: value.simulationTime ?? session.ready.simulationTime,
+            provenance: [session.preflight.engine],
+        };
+    }
+    async requireSession(projectPath) {
+        const canonical = await this.adapters.canonicalize(projectPath);
+        const session = this.sessions.get(canonical);
+        if (!session) {
+            throw new RuntimeToolError({
+                code: 'runtime-not-running',
+                stage: 'game',
+                message: 'No Run Session is active for this Project.',
+                projectPath: canonical,
+            });
+        }
+        if (session.state !== 'active') {
+            throw new RuntimeToolError({
+                code: 'runtime-invalid-state',
+                stage: 'game',
+                message: `The Run Session is ${session.state}; retry after it is active.`,
+                projectPath: canonical,
+            });
+        }
+        return session;
+    }
+    cleanupSession(session) {
+        session.cleanup ??= this.performCleanup(session);
+        return session.cleanup;
+    }
+    async performCleanup(session) {
+        if (session.state === 'stopped')
+            return;
+        session.state = 'stopping';
+        const failures = [];
+        await session.browser.close().catch((error) => failures.push(`browser: ${message(error)}`));
+        await session.devServer.stop().catch((error) => failures.push(`dev-server: ${message(error)}`));
+        session.state = 'stopped';
+        if (failures.length > 0) {
+            throw new RuntimeToolError({
+                code: 'runtime-operation-failed',
+                stage: 'cleanup',
+                message: `Could not prove Run Session cleanup: ${failures.join('; ')}`,
+                projectPath: session.preflight.projectPath,
+                diagnostics: { failures, ...session.devServer.diagnostics() },
+            });
+        }
+    }
+    async failSession(session, _error) {
+        this.sessions.delete(session.preflight.projectPath);
+        await this.cleanupSession(session).catch(() => { });
+    }
+}
+export function createDefaultRuntimeSessionManager() {
+    return new RuntimeSessionManager({
+        canonicalize: async (projectPath) => {
+            try {
+                return await realpath(projectPath);
+            }
+            catch (error) {
+                if (error.code === 'ENOENT')
+                    return path.resolve(projectPath);
+                throw new RuntimeToolError({
+                    code: 'runtime-prerequisite-missing',
+                    stage: 'project',
+                    message: `Project path is not accessible: ${message(error)}`,
+                    projectPath,
+                });
+            }
+        },
+        preflight: preflightRuntimeProject,
+        startDevServer: startRuntimeDevServer,
+        startBrowser: startRuntimeBrowser,
+    });
+}

package/dist/mcp/scaffolds.js

@@ -1,6 +1,7 @@
 import { access, mkdir, writeFile } from 'node:fs/promises';
 import path from 'node:path';
-import { assertSafeSlug } from './project-path.js';
+import { activeArchetypeId, discoverArchetypes, pickArchetype } from './archetypes.js';
+import { WaicaToolError, assertSafeSlug } from './project-path.js';
 function nameWords(name) {
     return name
         .trim()
@@ -31,11 +32,6 @@ function componentTemplate(name) {
 // Project-owned behavior — loaded by the shipped game and editor Play.
 export class ${Class} extends Component {
   static override componentName = '${Class}'
-  static override params = {
-    speed: { label: 'Speed', min: 0, max: 30, step: 0.5 },
-  }
-
-  speed = 5
 
   override onUpdate(dt: number): void {
     // Add this component's per-frame behavior here.
@@ -104,6 +100,75 @@ defineStates('${role}', {
 })
 `;
 }
+/**
+ * Prefab directory under src/ per type — the editor's PREFAB_DIRS read the
+ * other way round. Duplicated here for the same reason every template above
+ * is: the published server cannot import the private editor package, so a
+ * parity test holds the two copies together instead of the type system.
+ */
+const PREFAB_DIRECTORIES = {
+    character: 'characters',
+    object: 'objects',
+    tile: 'tiles',
+};
+const IDENTITIES = ['player', 'enemy', 'npc', 'custom'];
+const DEFAULT_SPRITE = { width: 1, height: 1, color: 0x8ecae6 };
+/** Mirrors the editor's IDENTITY_EXTRAS: what an identity is born with. */
+const IDENTITY_EXTRAS = {
+    player: [
+        { type: 'Respawnable' },
+        { type: 'Health', props: { invulnerability: 1 } },
+        { type: 'OutOfBounds' },
+    ],
+    enemy: [{ type: 'Hazard' }, { type: 'Health', props: { max: 1 } }],
+    npc: [],
+    custom: [],
+};
+/**
+ * The editor's newPrefabComponents, with the role handed in instead of read
+ * from the engine's global registry — this server resolves the archetype
+ * itself and never installs a bundle into its own process.
+ */
+function prefabComponents(type, role, definition, identity) {
+    switch (type) {
+        case 'character': {
+            const driver = definition?.driver ? [{ type: definition.driver }] : [];
+            return [
+                { type: 'Sprite', props: { ...DEFAULT_SPRITE, layer: 2 } },
+                {
+                    type: 'StateMachine',
+                    props: {
+                        role,
+                        initial: definition?.graph?.initial ?? '',
+                        states: definition?.graph?.states ?? {},
+                    },
+                },
+                ...driver,
+                ...(identity ? IDENTITY_EXTRAS[identity] : []),
+                { type: 'Hitbox', props: { width: 0.9, height: 0.95 } },
+            ];
+        }
+        case 'object':
+            return [
+                { type: 'Sprite', props: { ...DEFAULT_SPRITE, layer: 1 } },
+                { type: 'Hitbox', props: { width: 1, height: 1 } },
+            ];
+        case 'tile':
+            return [
+                { type: 'Sprite', props: { ...DEFAULT_SPRITE } },
+                { type: 'Solid', props: { width: 1, height: 1 } },
+            ];
+    }
+}
+/** The active archetype's roles — the only ones a scaffolded character may adopt. */
+async function archetypeRoles(projectPath) {
+    const activeId = await activeArchetypeId(projectPath);
+    const available = await discoverArchetypes(projectPath, undefined, [], activeId ? [activeId] : []);
+    return pickArchetype(available, activeId, projectPath).manifest.bundle.roles;
+}
+function invalidInput(projectPath, message) {
+    return new WaicaToolError({ code: 'invalid-input', message, projectPath });
+}
 const UI_TEMPLATE = `<style>
   .my-ui {
     position: absolute;
@@ -133,6 +198,61 @@ export async function scaffoldComponent(projectPath, name) {
     const className = componentClassName(name);
     return { ...(await writeOnce(projectPath, componentFilePath(name), componentTemplate(name))), className };
 }
+/**
+ * A starter prefab of the given type, byte-identical to what the editor
+ * writes for the same inputs — for roles the active archetype defines. The
+ * editor also accepts a project's own custom roles (defineRole); this
+ * function does not, and rejects them instead of guessing (see the
+ * unknown-role error below). The caller names it: no auto-numbering, and an
+ * existing file is left exactly as it is.
+ */
+export async function scaffoldPrefab(projectPath, name, type, role, identity) {
+    assertSafeSlug(name, 'name');
+    // A plain index lookup on an object literal lets inherited
+    // Object.prototype keys ('toString', 'constructor', 'valueOf', …) through
+    // as a truthy "directory" — Object.hasOwn keeps this to the type's own keys.
+    if (!Object.hasOwn(PREFAB_DIRECTORIES, type)) {
+        throw invalidInput(projectPath, `type must be one of ${Object.keys(PREFAB_DIRECTORIES).join(', ')}.`);
+    }
+    const prefabType = type;
+    const directory = PREFAB_DIRECTORIES[prefabType];
+    if (prefabType !== 'character' && (role !== undefined || identity !== undefined)) {
+        throw invalidInput(projectPath, `role and identity are character-only: a ${prefabType} prefab has neither.`);
+    }
+    if (identity !== undefined && !IDENTITIES.includes(identity)) {
+        throw invalidInput(projectPath, `identity must be one of ${IDENTITIES.join(', ')}.`);
+    }
+    // The editor's creation dialog never lets a non-player identity keep the
+    // player's role: picking "enemy" forces a movement-role pick too. Defaulting
+    // to 'player' here would silently hand an enemy/npc/custom the player's own
+    // driver instead of the role that identity is supposed to move it with.
+    if (identity !== undefined && identity !== 'player' && role === undefined) {
+        throw invalidInput(projectPath, `role is required when identity is "${identity}": the "player" default only applies when identity is "player" or omitted.`);
+    }
+    let definition;
+    // Same default the editor's creation dialog starts from.
+    const roleName = role ?? 'player';
+    if (prefabType === 'character') {
+        const roles = await archetypeRoles(projectPath);
+        definition = roles[roleName];
+        if (!definition) {
+            // Falling back to an empty graph would write a character that stands
+            // still in Play and says nothing about why.
+            throw new WaicaToolError({
+                code: 'unknown-role',
+                message: `Unknown role "${roleName}". Available roles: ${Object.keys(roles).sort().join(', ')}.`,
+                projectPath,
+                available: Object.keys(roles).sort(),
+            });
+        }
+    }
+    const prefab = {
+        waicaPrefab: 1,
+        type: prefabType,
+        components: prefabComponents(prefabType, roleName, definition, identity),
+    };
+    return writeOnce(projectPath, `src/${directory}/${name}.${prefabType}.json`, JSON.stringify(prefab, null, 2) + '\n');
+}
 export async function scaffoldRole(projectPath, role) {
     assertSafeSlug(role, 'role');
     return writeOnce(projectPath, `src/roles/${role}.ts`, roleTemplate(role));