@waica/cli 0.4.2 → 0.6.0

package/dist/mcp/server.js

@@ -6,7 +6,10 @@ import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextpro
 import { createProject } from './create-project.js';
 import { describeArchetype, listComponents, projectSummary, } from './introspection.js';
 import { ABSOLUTE_PATH_MESSAGE, WaicaToolError, assertAbsoluteProjectPath, requireWaicaProject, } from './project-path.js';
-import { scaffoldComponent, scaffoldRole, scaffoldState, scaffoldUi, } from './scaffolds.js';
+import { scaffoldComponent, scaffoldPrefab, scaffoldRole, scaffoldState, scaffoldUi, } from './scaffolds.js';
+import { RuntimeToolError, } from './runtime-service.js';
+import { createDefaultRuntimeSessionManager } from './runtime-session-manager.js';
+import { ProjectComponentLoader } from './project-component-loader.js';
 import { validateProject } from './validation.js';
 const PROJECT_PATH = {
     type: 'string',
@@ -69,6 +72,29 @@ export const TOOLS = [
         inputSchema: schema({ name: { type: 'string', minLength: 1 } }, ['name']),
         annotations: { destructiveHint: false, idempotentHint: true, openWorldHint: false },
     },
+    {
+        name: 'scaffold_prefab',
+        description: 'Create the editor-compatible starter prefab for a character, object or tile.',
+        inputSchema: schema({
+            name: { type: 'string', minLength: 1, description: 'Prefab file name, without the type suffix.' },
+            type: {
+                type: 'string',
+                enum: ['character', 'object', 'tile'],
+                description: 'Prefab category; it decides the directory and the file suffix.',
+            },
+            role: {
+                type: 'string',
+                minLength: 1,
+                description: 'Character role from the active archetype (characters only); defaults to player.',
+            },
+            identity: {
+                type: 'string',
+                enum: ['player', 'enemy', 'npc', 'custom'],
+                description: 'What the character is to the game (characters only); adds its starter components.',
+            },
+        }, ['name', 'type']),
+        annotations: { destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    },
     {
         name: 'scaffold_role',
         description: 'Create the editor-compatible starter for a custom character role.',
@@ -95,7 +121,92 @@ export const TOOLS = [
         inputSchema: schema({ name: { type: 'string', minLength: 1 } }, ['name']),
         annotations: { destructiveHint: false, idempotentHint: true, openWorldHint: false },
     },
+    {
+        name: 'start_project',
+        description: 'Start or reuse a browser-backed Run Session for a trusted Waica Project.',
+        inputSchema: schema({
+            browser_executable_path: { type: 'string', minLength: 1 },
+            headless: { type: 'boolean', default: true },
+            viewport: {
+                type: 'object',
+                properties: {
+                    width: { type: 'integer', minimum: 1 },
+                    height: { type: 'integer', minimum: 1 },
+                },
+                required: ['width', 'height'],
+                additionalProperties: false,
+            },
+            timeout_ms: { type: 'integer', minimum: 1_000, maximum: 120_000, default: 30_000 },
+        }),
+        annotations: { destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    },
+    {
+        name: 'stop_project',
+        description: 'Stop a Project Run Session and all browser and process resources it owns.',
+        inputSchema: schema({}),
+        annotations: { destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    },
+    {
+        name: 'inspect_runtime',
+        description: 'Read a filtered Runtime Snapshot from a running Project.',
+        inputSchema: schema({
+            entity_ids: { type: 'array', items: { type: 'string' } },
+            entity_names: { type: 'array', items: { type: 'string' } },
+            component_types: { type: 'array', items: { type: 'string' } },
+        }),
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    },
+    {
+        name: 'control_runtime',
+        description: 'Inject a semantic action or change deterministic frame control for a Run Session.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                project_path: PROJECT_PATH,
+                operation: {
+                    type: 'string',
+                    enum: ['press', 'hold', 'release', 'pause', 'resume', 'step'],
+                },
+                action: { type: 'string', minLength: 1 },
+                dt: { type: 'number', exclusiveMinimum: 0, maximum: 0.1 },
+                frames: { type: 'integer', minimum: 1, maximum: 600 },
+            },
+            required: ['project_path', 'operation'],
+            additionalProperties: false,
+            oneOf: [
+                {
+                    properties: { operation: { enum: ['press', 'hold', 'release'] } },
+                    required: ['action'],
+                    not: { anyOf: [{ required: ['dt'] }, { required: ['frames'] }] },
+                },
+                {
+                    properties: { operation: { enum: ['pause', 'resume'] } },
+                    not: {
+                        anyOf: [{ required: ['action'] }, { required: ['dt'] }, { required: ['frames'] }],
+                    },
+                },
+                {
+                    properties: { operation: { const: 'step' } },
+                    not: { anyOf: [{ required: ['action'] }] },
+                },
+            ],
+        },
+        annotations: { destructiveHint: false, idempotentHint: false, openWorldHint: false },
+    },
+    {
+        name: 'capture_screenshot',
+        description: 'Capture the composited Waica Game surface from a running Project.',
+        inputSchema: schema({}),
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    },
 ];
+const RUNTIME_TOOL_NAMES = new Set([
+    'start_project',
+    'stop_project',
+    'inspect_runtime',
+    'control_runtime',
+    'capture_screenshot',
+]);
 function requiredString(args, name, projectPath = '') {
     const value = args[name];
     if (typeof value === 'string' && value.length > 0)
@@ -106,11 +217,131 @@ function requiredString(args, name, projectPath = '') {
         projectPath,
     });
 }
-async function execute(name, args) {
+function invalidRuntimeInput(name, projectPath, message) {
+    throw new RuntimeToolError({
+        code: 'runtime-operation-failed',
+        stage: name === 'control_runtime' ? 'control' : 'project',
+        message,
+        projectPath,
+    });
+}
+function assertOnlyRuntimeFields(name, args, allowed, projectPath) {
+    const extras = Object.keys(args).filter((key) => !allowed.includes(key));
+    if (extras.length > 0) {
+        invalidRuntimeInput(name, projectPath, `Unexpected properties: ${extras.sort().join(', ')}.`);
+    }
+}
+function assertStringArray(name, args, field, projectPath) {
+    const value = args[field];
+    if (value !== undefined && (!Array.isArray(value) || value.some((entry) => typeof entry !== 'string'))) {
+        invalidRuntimeInput(name, projectPath, `${field} must be an array of strings.`);
+    }
+}
+function validateRuntimeArguments(name, args, projectPath) {
+    switch (name) {
+        case 'start_project': {
+            assertOnlyRuntimeFields(name, args, ['project_path', 'browser_executable_path', 'headless', 'viewport', 'timeout_ms'], projectPath);
+            if (args.browser_executable_path !== undefined &&
+                (typeof args.browser_executable_path !== 'string' || args.browser_executable_path.length === 0)) {
+                invalidRuntimeInput(name, projectPath, 'browser_executable_path must be a nonempty string.');
+            }
+            if (args.headless !== undefined && typeof args.headless !== 'boolean') {
+                invalidRuntimeInput(name, projectPath, 'headless must be a boolean.');
+            }
+            if (args.timeout_ms !== undefined) {
+                const timeout = args.timeout_ms;
+                if (typeof timeout !== 'number' || !Number.isInteger(timeout) || timeout < 1_000 || timeout > 120_000) {
+                    invalidRuntimeInput(name, projectPath, 'timeout_ms must be an integer from 1,000 through 120,000.');
+                }
+            }
+            if (args.viewport !== undefined) {
+                if (!args.viewport || typeof args.viewport !== 'object' || Array.isArray(args.viewport)) {
+                    invalidRuntimeInput(name, projectPath, 'viewport must contain width and height.');
+                }
+                const viewport = args.viewport;
+                const keys = Object.keys(viewport);
+                if (keys.some((key) => key !== 'width' && key !== 'height') ||
+                    keys.length !== 2 ||
+                    typeof viewport.width !== 'number' ||
+                    typeof viewport.height !== 'number' ||
+                    !Number.isInteger(viewport.width) ||
+                    !Number.isInteger(viewport.height) ||
+                    viewport.width <= 0 ||
+                    viewport.height <= 0 ||
+                    viewport.width * viewport.height > 1_000_000) {
+                    invalidRuntimeInput(name, projectPath, 'viewport width and height must be positive integers totaling at most 1,000,000 pixels.');
+                }
+            }
+            return;
+        }
+        case 'stop_project':
+        case 'capture_screenshot':
+            assertOnlyRuntimeFields(name, args, ['project_path'], projectPath);
+            return;
+        case 'inspect_runtime':
+            assertOnlyRuntimeFields(name, args, ['project_path', 'entity_ids', 'entity_names', 'component_types'], projectPath);
+            assertStringArray(name, args, 'entity_ids', projectPath);
+            assertStringArray(name, args, 'entity_names', projectPath);
+            assertStringArray(name, args, 'component_types', projectPath);
+            return;
+        case 'control_runtime': {
+            assertOnlyRuntimeFields(name, args, ['project_path', 'operation', 'action', 'dt', 'frames'], projectPath);
+            const operation = args.operation;
+            if (!['press', 'hold', 'release', 'pause', 'resume', 'step'].includes(String(operation))) {
+                invalidRuntimeInput(name, projectPath, 'operation is not a supported runtime control operation.');
+            }
+            if (operation === 'press' || operation === 'hold' || operation === 'release') {
+                if (typeof args.action !== 'string' || args.action.length === 0) {
+                    invalidRuntimeInput(name, projectPath, `${operation} requires a nonempty action.`);
+                }
+                if (args.dt !== undefined || args.frames !== undefined) {
+                    invalidRuntimeInput(name, projectPath, `${operation} does not accept dt or frames.`);
+                }
+            }
+            else if (operation === 'pause' || operation === 'resume') {
+                if (args.action !== undefined || args.dt !== undefined || args.frames !== undefined) {
+                    invalidRuntimeInput(name, projectPath, `${operation} accepts no additional fields.`);
+                }
+            }
+            else {
+                if (args.action !== undefined)
+                    invalidRuntimeInput(name, projectPath, 'step does not accept action.');
+                if (args.dt !== undefined &&
+                    (typeof args.dt !== 'number' || !Number.isFinite(args.dt) || args.dt <= 0 || args.dt > 0.1)) {
+                    invalidRuntimeInput(name, projectPath, 'dt must be finite and greater than 0 and at most 0.1.');
+                }
+                if (args.frames !== undefined &&
+                    (typeof args.frames !== 'number' || !Number.isInteger(args.frames) || args.frames < 1 || args.frames > 600)) {
+                    invalidRuntimeInput(name, projectPath, 'frames must be an integer from 1 through 600.');
+                }
+            }
+            return;
+        }
+    }
+}
+async function execute(name, args, runtime, signal, componentLoader) {
+    const isRuntimeTool = RUNTIME_TOOL_NAMES.has(name);
+    const rawProjectPath = args.project_path;
+    if (isRuntimeTool && (typeof rawProjectPath !== 'string' || rawProjectPath.length === 0)) {
+        invalidRuntimeInput(name, '', 'project_path must be a nonempty absolute path.');
+    }
     const projectPath = requiredString(args, 'project_path');
     // Keep this at the dispatch boundary so every tool has byte-identical
     // stdio-cwd semantics, including create_project.
-    assertAbsoluteProjectPath(projectPath);
+    if (isRuntimeTool) {
+        if (!path.isAbsolute(projectPath)) {
+            throw new RuntimeToolError({
+                code: 'runtime-prerequisite-missing',
+                stage: 'project',
+                message: ABSOLUTE_PATH_MESSAGE,
+                projectPath,
+            });
+        }
+        validateRuntimeArguments(name, args, projectPath);
+    }
+    else {
+        assertAbsoluteProjectPath(projectPath);
+    }
     switch (name) {
         case 'create_project': {
             const start = args.start === undefined ? 'demo' : requiredString(args, 'start', projectPath);
@@ -130,7 +361,7 @@ async function execute(name, args) {
         case 'project_summary':
             return projectSummary(projectPath);
         case 'validate_project':
-            return validateProject(projectPath);
+            return validateProject(projectPath, { signal, componentLoader });
         case 'scaffold_component': {
             const check = await requireWaicaProject(projectPath);
             return {
@@ -140,6 +371,15 @@ async function execute(name, args) {
                 warnings: [],
             };
         }
+        case 'scaffold_prefab': {
+            const check = await requireWaicaProject(projectPath);
+            return {
+                ...(await scaffoldPrefab(projectPath, requiredString(args, 'name', projectPath), requiredString(args, 'type', projectPath), args.role === undefined ? undefined : requiredString(args, 'role', projectPath), args.identity === undefined ? undefined : requiredString(args, 'identity', projectPath))),
+                notes: check.notes,
+                provenance: [],
+                warnings: [],
+            };
+        }
         case 'scaffold_role': {
             const check = await requireWaicaProject(projectPath);
             return {
@@ -167,6 +407,39 @@ async function execute(name, args) {
                 warnings: [],
             };
         }
+        case 'start_project':
+            return runtime.start({
+                projectPath,
+                ...(typeof args.browser_executable_path === 'string'
+                    ? { browserExecutablePath: args.browser_executable_path }
+                    : {}),
+                ...(typeof args.headless === 'boolean' ? { headless: args.headless } : {}),
+                ...(args.viewport && typeof args.viewport === 'object'
+                    ? { viewport: args.viewport }
+                    : {}),
+                ...(typeof args.timeout_ms === 'number' ? { timeoutMs: args.timeout_ms } : {}),
+            });
+        case 'stop_project':
+            return runtime.stop(projectPath);
+        case 'inspect_runtime':
+            return runtime.inspect({
+                projectPath,
+                ...(Array.isArray(args.entity_ids) ? { entityIds: args.entity_ids } : {}),
+                ...(Array.isArray(args.entity_names) ? { entityNames: args.entity_names } : {}),
+                ...(Array.isArray(args.component_types)
+                    ? { componentTypes: args.component_types }
+                    : {}),
+            });
+        case 'control_runtime':
+            return runtime.control({
+                projectPath,
+                operation: requiredString(args, 'operation', projectPath),
+                ...(typeof args.action === 'string' ? { action: args.action } : {}),
+                ...(typeof args.dt === 'number' ? { dt: args.dt } : {}),
+                ...(typeof args.frames === 'number' ? { frames: args.frames } : {}),
+            });
+        case 'capture_screenshot':
+            return runtime.captureScreenshot(projectPath);
         default:
             throw new WaicaToolError({
                 code: 'unknown-tool',
@@ -186,11 +459,39 @@ function result(payload, isError = false) {
         ...(isError ? { isError: true } : {}),
     };
 }
-function errorResult(error, args) {
+function screenshotResult(screenshot) {
+    const metadata = jsonSafe(screenshot.metadata);
+    return {
+        content: [
+            { type: 'text', text: JSON.stringify(metadata, null, 2) },
+            { type: 'image', mimeType: 'image/png', data: screenshot.data },
+        ],
+        structuredContent: metadata,
+    };
+}
+function errorResult(error, args, toolName) {
     const projectPath = typeof args.project_path === 'string' ? args.project_path : '';
+    if (error instanceof RuntimeToolError) {
+        return result({ error: error.body }, true);
+    }
     if (error instanceof WaicaToolError) {
         return result({ error: error.body, provenance: [] }, true);
     }
+    if (RUNTIME_TOOL_NAMES.has(toolName)) {
+        const stage = toolName === 'control_runtime'
+            ? 'control'
+            : toolName === 'stop_project'
+                ? 'cleanup'
+                : 'game';
+        return result({
+            error: {
+                code: 'runtime-operation-failed',
+                stage,
+                message: error instanceof Error ? error.message : String(error),
+                projectPath,
+            },
+        }, true);
+    }
     return result({
         error: {
             code: 'tool-error',
@@ -224,7 +525,9 @@ function shippedVersion() {
         directory = parent;
     }
 }
-export function createWaicaMcpServer() {
+export function createWaicaMcpServer(options = {}) {
+    const runtime = options.runtime ?? createDefaultRuntimeSessionManager();
+    const componentLoader = options.componentLoader ?? new ProjectComponentLoader();
     const server = new Server(
     // The name stays fixed: it identifies the server to the host, not the
     // package that happens to carry it.
@@ -233,15 +536,33 @@ export function createWaicaMcpServer() {
         instructions: 'Operate on user Waica projects through absolute project_path values. Keep editing JSON and TypeScript with the host file tools.',
     });
     server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
-    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
         const args = (request.params.arguments ?? {});
         try {
-            return result(await execute(request.params.name, args));
+            const executed = await execute(request.params.name, args, runtime, extra.signal, componentLoader);
+            return request.params.name === 'capture_screenshot'
+                ? screenshotResult(executed)
+                : result(executed);
         }
         catch (error) {
-            return errorResult(error, args);
+            if (extra.signal.aborted)
+                throw (extra.signal.reason ?? error);
+            return errorResult(error, args, request.params.name);
         }
     });
+    let cleanup;
+    const cleanupResources = () => {
+        cleanup ??= Promise.all([runtime.close(), componentLoader.close()]).then(() => undefined);
+        return cleanup;
+    };
+    server.onclose = () => {
+        void cleanupResources();
+    };
+    const closeProtocol = server.close.bind(server);
+    server.close = async () => {
+        await cleanupResources();
+        await closeProtocol();
+    };
     return server;
 }
 export { ABSOLUTE_PATH_MESSAGE };

package/dist/mcp/template/src/characters/player.character.json

@@ -112,6 +112,23 @@
                 "to": "idle"
               }
             ]
+          },
+          "dead": {
+            "clip": "idle",
+            "transitions": [
+              {
+                "on": "timer:0.8",
+                "to": "idle"
+              }
+            ]
+          },
+          "*": {
+            "transitions": [
+              {
+                "on": "signal:death",
+                "to": "dead"
+              }
+            ]
           }
         }
       }
@@ -124,9 +141,19 @@
       }
     },
     {
-      "type": "Respawnable",
+      "type": "Respawnable"
+    },
+    {
+      "type": "Health",
+      "props": {
+        "max": 3,
+        "invulnerability": 1
+      }
+    },
+    {
+      "type": "OutOfBounds",
       "props": {
-        "killY": -12
+        "minY": -12
       }
     }
   ]

package/dist/mcp/template/src/characters/slime.character.json

@@ -56,6 +56,12 @@
         "stompable": true,
         "bounce": 10
       }
+    },
+    {
+      "type": "Health",
+      "props": {
+        "max": 1
+      }
     }
   ]
 }

package/dist/mcp/template/src/main.ts

@@ -14,7 +14,12 @@ import settings from './game.json'
 
 // Your components, roles and state code extend the installed archetype
 // baseline when main() imports them.
-const projectCode = import.meta.glob(['./components/*.ts', './roles/*.ts', './states/*.ts'])
+const projectCode = import.meta.glob([
+  './components/*.ts',
+  './roles/*.ts',
+  './states/*.ts',
+  '!**/*.test.ts',
+])
 
 // Your prefabs ARE these files (saved by the editor, or hand-edited — they're
 // just JSON). Nothing else: delete one and the game stops knowing about it.