@waica/cli 0.5.0 → 0.6.0

package/dist/mcp/project-component-runner.js

@@ -0,0 +1,237 @@
+import { existsSync, realpathSync } from 'node:fs';
+import * as nodeModule from 'node:module';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+const PROTOCOL_VERSION = 1;
+const { createRequire } = nodeModule;
+const hostRequire = createRequire(import.meta.url);
+const FALLBACK_PACKAGES = new Set([
+    '@waica/engine',
+    '@waica/behaviors',
+    '@waica/archetype-platformer',
+]);
+const FALLBACK_SPECIFIERS = new Set([...FALLBACK_PACKAGES, 'three']);
+const REF_KINDS = new Set(['prefab', 'clip', 'action', 'stat']);
+const RELATIVE_EXTENSIONS = ['.ts', '.tsx', '.js'];
+function record(value) {
+    return value && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : {};
+}
+function installedPackage(projectPath, name) {
+    for (let current = projectPath;; current = path.dirname(current)) {
+        if (existsSync(path.join(current, 'node_modules', ...name.split('/'), 'package.json'))) {
+            return true;
+        }
+        const parent = path.dirname(current);
+        if (parent === current)
+            return false;
+    }
+}
+function relativeCandidates(unresolvedPath) {
+    const candidates = [
+        ...RELATIVE_EXTENSIONS.map((extension) => `${unresolvedPath}${extension}`),
+        ...RELATIVE_EXTENSIONS.map((extension) => path.join(unresolvedPath, `index${extension}`)),
+    ];
+    if (unresolvedPath.endsWith('.js')) {
+        const withoutJs = unresolvedPath.slice(0, -'.js'.length);
+        candidates.unshift(`${withoutJs}.ts`, `${withoutJs}.tsx`);
+    }
+    return candidates;
+}
+function resolveRelativeCandidate(unresolvedPath) {
+    return relativeCandidates(unresolvedPath).find((candidate) => existsSync(candidate));
+}
+function installProjectResolution(projectPath, fallbackEntries) {
+    if (typeof nodeModule.registerHooks !== 'function') {
+        throw new Error('node:module registerHooks is unavailable');
+    }
+    const projectRequire = createRequire(path.join(projectPath, 'package.json'));
+    // Resolve before registering the hook. Calling createRequire.resolve from
+    // inside a synchronous resolve hook recursively invokes that same hook.
+    // Failures stay attached to their package and surface only when an entry
+    // actually imports it, matching the previous per-package bridge behavior.
+    const packageEntries = new Map();
+    for (const specifier of FALLBACK_PACKAGES) {
+        try {
+            packageEntries.set(specifier, installedPackage(projectPath, specifier)
+                ? projectRequire.resolve(specifier)
+                : (fallbackEntries[specifier] ?? hostRequire.resolve(specifier)));
+        }
+        catch (error) {
+            packageEntries.set(specifier, error instanceof Error ? error : new Error(String(error)));
+        }
+    }
+    const fallbackRoots = [...FALLBACK_PACKAGES]
+        .map((specifier) => fallbackEntries[specifier])
+        .filter((entry) => typeof entry === 'string')
+        .map((entry) => realpathSync(path.dirname(entry)));
+    const fromFallback = (parentURL) => {
+        if (!parentURL?.startsWith('file:'))
+            return false;
+        const parent = realpathSync(fileURLToPath(parentURL));
+        return fallbackRoots.some((root) => parent === root || parent.startsWith(`${root}${path.sep}`));
+    };
+    nodeModule.registerHooks({
+        resolve(specifier, context, nextResolve) {
+            const dependencyEntry = fallbackEntries[specifier];
+            if (dependencyEntry && fromFallback(context.parentURL)) {
+                return { url: pathToFileURL(dependencyEntry).href, shortCircuit: true };
+            }
+            const packageEntry = packageEntries.get(specifier);
+            if (packageEntry instanceof Error)
+                throw packageEntry;
+            if (packageEntry) {
+                return { url: pathToFileURL(packageEntry).href, shortCircuit: true };
+            }
+            if (specifier.startsWith('.') && context.parentURL) {
+                const unresolved = new URL(specifier, context.parentURL);
+                try {
+                    return nextResolve(specifier, context);
+                }
+                catch (error) {
+                    const fallback = resolveRelativeCandidate(fileURLToPath(unresolved));
+                    if (!fallback)
+                        throw error;
+                    return { url: pathToFileURL(fallback).href, shortCircuit: true };
+                }
+            }
+            return nextResolve(specifier, context);
+        },
+    });
+}
+function errorChain(error) {
+    const errors = [];
+    let current = error;
+    const seen = new Set();
+    while (current instanceof Error && !seen.has(current)) {
+        errors.push(current);
+        seen.add(current);
+        current = current.cause;
+    }
+    return errors;
+}
+function unsupportedByNode(error) {
+    for (const candidate of errorChain(error)) {
+        const code = candidate.code;
+        if (code === 'ERR_UNKNOWN_FILE_EXTENSION' ||
+            code === 'ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX') {
+            return true;
+        }
+        if (/not supported in strip-only mode|unsupported TypeScript syntax|unknown file extension/i.test(candidate.message)) {
+            return true;
+        }
+    }
+    return false;
+}
+function causeText(error) {
+    if (!(error instanceof Error))
+        return String(error);
+    const code = error.code;
+    return `${code ? `${code}: ` : ''}${error.message}`;
+}
+function stringDefaults(Class) {
+    try {
+        return Object.fromEntries(Object.entries(new Class()).filter((entry) => typeof entry[1] === 'string'));
+    }
+    catch {
+        return {};
+    }
+}
+function componentRows(loaded, relativeFile) {
+    const rows = [];
+    for (const value of Object.values(loaded)) {
+        if (typeof value !== 'function' || !Object.hasOwn(value, 'componentName'))
+            continue;
+        const Class = value;
+        if (typeof Class.componentName !== 'string' || !Class.componentName)
+            continue;
+        const defaults = stringDefaults(Class);
+        const params = [];
+        for (const [name, rawSpec] of Object.entries(record(Class.params))) {
+            const spec = record(rawSpec);
+            if (typeof spec.ref !== 'string' || !REF_KINDS.has(spec.ref))
+                continue;
+            params.push({
+                name,
+                ref: spec.ref,
+                hasOptions: spec.options !== undefined,
+                ...(Object.hasOwn(defaults, name) ? { default: defaults[name] } : {}),
+            });
+        }
+        const hasUpdateAfter = Class.updateAfter !== undefined;
+        if (hasUpdateAfter &&
+            (!Array.isArray(Class.updateAfter) ||
+                Class.updateAfter.some((target) => typeof target !== 'string'))) {
+            throw new Error(`Component "${Class.componentName}" updateAfter must be an array of strings.`);
+        }
+        rows.push({
+            name: Class.componentName,
+            file: relativeFile,
+            params,
+            hasOnUpdate: typeof Class.prototype?.onUpdate === 'function',
+            hasUpdateAfter,
+            updateAfter: hasUpdateAfter ? [...Class.updateAfter] : [],
+        });
+    }
+    return rows;
+}
+function validRequest(value) {
+    const candidate = record(value);
+    const fallbacks = record(candidate.fallbackEntries);
+    return (candidate.kind === 'load-project-entry' &&
+        candidate.version === PROTOCOL_VERSION &&
+        typeof candidate.token === 'string' &&
+        candidate.token.length > 0 &&
+        typeof candidate.projectPath === 'string' &&
+        path.isAbsolute(candidate.projectPath) &&
+        typeof candidate.entryFile === 'string' &&
+        path.isAbsolute(candidate.entryFile) &&
+        typeof candidate.relativeFile === 'string' &&
+        candidate.relativeFile.length > 0 &&
+        !!candidate.fallbackEntries &&
+        typeof candidate.fallbackEntries === 'object' &&
+        !Array.isArray(candidate.fallbackEntries) &&
+        Object.entries(fallbacks).every(([specifier, entry]) => FALLBACK_SPECIFIERS.has(specifier) &&
+            typeof entry === 'string' &&
+            path.isAbsolute(entry)));
+}
+function sendTerminal(message) {
+    if (!process.send)
+        process.exit(1);
+    process.send(message, (error) => process.exit(error ? 1 : 0));
+}
+async function execute(request) {
+    try {
+        installProjectResolution(request.projectPath, request.fallbackEntries);
+        const loaded = (await import(pathToFileURL(request.entryFile).href));
+        sendTerminal({
+            kind: 'project-entry-result',
+            version: PROTOCOL_VERSION,
+            token: request.token,
+            ok: true,
+            components: componentRows(loaded, request.relativeFile),
+        });
+    }
+    catch (error) {
+        sendTerminal({
+            kind: 'project-entry-result',
+            version: PROTOCOL_VERSION,
+            token: request.token,
+            ok: false,
+            code: unsupportedByNode(error)
+                ? 'component-load-unsupported'
+                : 'component-load-failed',
+            message: causeText(error),
+        });
+    }
+}
+if (!process.send) {
+    throw new Error('Project component runner requires an IPC channel.');
+}
+process.send({ kind: 'project-entry-ready', version: PROTOCOL_VERSION });
+process.once('message', (message) => {
+    if (!validRequest(message))
+        process.exit(1);
+    void execute(message);
+});

package/dist/mcp/runtime-browser.js

@@ -0,0 +1,336 @@
+import { chromium, } from 'playwright-core';
+import { RuntimeToolError } from './runtime-service.js';
+export const RUNTIME_BRIDGE_SYMBOL_KEY = '@waica/runtime-bridge/v1';
+export const MINIMUM_RUNTIME_ENGINE_VERSION = '0.5.0';
+/** Serialized by Playwright and installed before any Project module executes. */
+export function installRuntimeBridgeActivation() {
+    const key = Symbol.for('@waica/runtime-bridge/v1');
+    const activation = {
+        protocolVersion: 1,
+        current: null,
+        failure: null,
+        register(bridge) {
+            if (this.current && this.current !== bridge) {
+                this.failure = {
+                    code: 'multiple-games',
+                    message: 'Exactly one live Game may register with a Run Session.',
+                };
+                return;
+            }
+            this.current = bridge;
+        },
+        unregister(bridge) {
+            if (this.current === bridge)
+                this.current = null;
+        },
+    };
+    Object.defineProperty(globalThis, key, {
+        configurable: true,
+        value: activation,
+    });
+}
+function boundedMessage(value) {
+    const text = value instanceof Error ? `${value.name}: ${value.message}` : String(value);
+    return text.length <= 4_096 ? text : `${text.slice(-4_096)}`;
+}
+function runtimeError(preflight, stage, message, diagnostics, code = 'runtime-start-failed') {
+    return new RuntimeToolError({
+        code,
+        stage,
+        message,
+        projectPath: preflight.projectPath,
+        ...(diagnostics ? { diagnostics } : {}),
+    });
+}
+function delay(milliseconds) {
+    return new Promise((resolve) => setTimeout(resolve, milliseconds));
+}
+async function readinessProbe(page) {
+    return page.evaluate(() => {
+        const hook = globalThis[Symbol.for('@waica/runtime-bridge/v1')];
+        if (!hook?.current) {
+            if (hook?.failure)
+                return { status: 'failure', message: hook.failure.message };
+            return { status: 'waiting' };
+        }
+        if (hook.failure)
+            return { status: 'failure', message: hook.failure.message };
+        try {
+            const bridge = hook.current;
+            return {
+                status: 'ready',
+                metadata: bridge.metadata(),
+                initialSnapshot: bridge.inspect(),
+            };
+        }
+        catch (error) {
+            return {
+                status: 'failure',
+                message: error instanceof Error ? error.message : String(error),
+            };
+        }
+    });
+}
+function bridgeReady(preflight, probe) {
+    const { metadata, initialSnapshot } = probe;
+    if (metadata.bridgeVersion !== 1) {
+        throw runtimeError(preflight, 'bridge', `Runtime Bridge protocol ${String(metadata.bridgeVersion)} is incompatible; protocol 1 is required.`, { minimumEngineVersion: MINIMUM_RUNTIME_ENGINE_VERSION }, 'runtime-incompatible');
+    }
+    if (metadata.mode !== 'paused' ||
+        metadata.frame !== 0 ||
+        metadata.simulationTime !== 0) {
+        throw runtimeError(preflight, 'game', 'The Runtime Bridge did not reach the required paused frame-zero baseline.', { metadata });
+    }
+    return {
+        engineVersion: metadata.engineVersion,
+        bridgeVersion: metadata.bridgeVersion,
+        mode: metadata.mode,
+        frame: metadata.frame,
+        simulationTime: metadata.simulationTime,
+        initialSnapshot,
+    };
+}
+class PlaywrightRuntimeBrowser {
+    preflight;
+    devServer;
+    browser;
+    context;
+    page;
+    lifecycle = {
+        reloading: () => { },
+        reloaded: () => { },
+        failed: () => { },
+    };
+    initialReady = false;
+    reloading = false;
+    closed = false;
+    readyValue;
+    browserErrors = [];
+    constructor(preflight, devServer, browser, context, page) {
+        this.preflight = preflight;
+        this.devServer = devServer;
+        this.browser = browser;
+        this.context = context;
+        this.page = page;
+        const recordError = (detail) => {
+            this.browserErrors.push(boundedMessage(detail));
+            if (this.browserErrors.length > 100)
+                this.browserErrors.shift();
+        };
+        page.on('pageerror', recordError);
+        page.on('console', (entry) => {
+            if (entry.type() === 'error')
+                recordError(entry.text());
+        });
+        page.on('crash', () => this.lifecycle.failed(new Error('Project page crashed.')));
+        page.on('close', () => {
+            if (!this.closed)
+                this.lifecycle.failed(new Error('Project page closed.'));
+        });
+        browser.on('disconnected', () => {
+            if (!this.closed)
+                this.lifecycle.failed(new Error('Browser disconnected.'));
+        });
+        page.on('framenavigated', (frame) => {
+            if (this.initialReady &&
+                frame === page.mainFrame() &&
+                !this.reloading &&
+                !this.closed) {
+                void this.handleReload();
+            }
+        });
+    }
+    async initialize() {
+        try {
+            await this.page.goto(this.devServer.url, {
+                waitUntil: 'load',
+                timeout: this.preflight.timeoutMs,
+            });
+        }
+        catch (error) {
+            throw runtimeError(this.preflight, 'page', `Could not load the Project page: ${boundedMessage(error)}`, this.diagnostics());
+        }
+        this.readyValue = await this.waitForReady();
+        this.initialReady = true;
+    }
+    async ready() {
+        if (!this.readyValue)
+            throw new Error('Runtime browser was not initialized.');
+        return this.readyValue;
+    }
+    async inspect(filters) {
+        return this.invokeBridge('inspect', {
+            ...(filters.entityIds ? { entity_ids: filters.entityIds } : {}),
+            ...(filters.entityNames ? { entity_names: filters.entityNames } : {}),
+            ...(filters.componentTypes ? { component_types: filters.componentTypes } : {}),
+        });
+    }
+    async control(request) {
+        return this.invokeBridge('control', request);
+    }
+    async captureScreenshot() {
+        this.assertOperational();
+        const geometry = await this.page.evaluate(() => {
+            const hook = globalThis[Symbol.for('@waica/runtime-bridge/v1')];
+            const bridge = hook.current;
+            const rect = bridge.surface.getBoundingClientRect();
+            return {
+                metadata: bridge.metadata(),
+                clip: { x: rect.x, y: rect.y, width: rect.width, height: rect.height },
+            };
+        });
+        const { width, height } = geometry.clip;
+        if (!Number.isFinite(width) ||
+            !Number.isFinite(height) ||
+            width <= 0 ||
+            height <= 0 ||
+            Math.ceil(width) * Math.ceil(height) > 1_000_000) {
+            throw runtimeError(this.preflight, 'game', 'The Game surface has invalid or oversized screenshot dimensions.', { clip: geometry.clip }, 'runtime-operation-failed');
+        }
+        const png = await this.page.screenshot({
+            type: 'png',
+            clip: geometry.clip,
+            animations: 'allow',
+            caret: 'hide',
+        });
+        const metadata = await this.invokeBridge('metadata', {});
+        return { ...metadata, data: png.toString('base64') };
+    }
+    async close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        await this.context.close().catch(() => { });
+        await this.browser.close().catch(() => { });
+    }
+    setLifecycleHandlers(handlers) {
+        this.lifecycle = handlers;
+    }
+    async waitForReady() {
+        const deadline = Date.now() + this.preflight.timeoutMs;
+        while (Date.now() <= deadline) {
+            if (this.closed || this.page.isClosed()) {
+                throw runtimeError(this.preflight, 'page', 'The Project page closed before Runtime Bridge readiness.', this.diagnostics());
+            }
+            const probe = await readinessProbe(this.page).catch((error) => ({
+                status: 'failure',
+                message: boundedMessage(error),
+            }));
+            if (probe.status === 'ready')
+                return bridgeReady(this.preflight, probe);
+            if (probe.status === 'failure') {
+                throw runtimeError(this.preflight, probe.message.includes('Exactly one live Game') ? 'game' : 'bridge', probe.message, this.diagnostics());
+            }
+            await delay(25);
+        }
+        const diagnostics = this.diagnostics();
+        if (this.browserErrors.length > 0) {
+            throw runtimeError(this.preflight, 'page', 'The Project page did not reach Runtime Bridge readiness.', diagnostics);
+        }
+        throw runtimeError(this.preflight, 'bridge', 'Timed out waiting for Runtime Bridge protocol 1 and one live Game.', { ...diagnostics, minimumEngineVersion: MINIMUM_RUNTIME_ENGINE_VERSION }, this.preflight.engine.version === MINIMUM_RUNTIME_ENGINE_VERSION
+            ? 'runtime-start-failed'
+            : 'runtime-incompatible');
+    }
+    async invokeBridge(operation, argument) {
+        this.assertOperational();
+        const response = await this.page.evaluate(({ operation, argument }) => {
+            const hook = globalThis[Symbol.for('@waica/runtime-bridge/v1')];
+            if (!hook?.current || hook.failure) {
+                return {
+                    ok: false,
+                    error: {
+                        code: 'runtime-invalid-state',
+                        stage: 'game',
+                        message: hook?.failure?.message ?? 'No live Game is registered.',
+                    },
+                };
+            }
+            try {
+                const bridge = hook.current;
+                const value = operation === 'inspect'
+                    ? bridge.inspect(argument)
+                    : operation === 'control'
+                        ? bridge.control(argument)
+                        : bridge.metadata();
+                return { ok: true, value };
+            }
+            catch (error) {
+                const detail = error;
+                return {
+                    ok: false,
+                    error: {
+                        code: typeof detail.code === 'string' ? detail.code : 'runtime-operation-failed',
+                        stage: typeof detail.stage === 'string' ? detail.stage : 'control',
+                        message: typeof detail.message === 'string' ? detail.message : String(error),
+                        ...(Array.isArray(detail.availableActions)
+                            ? { availableActions: detail.availableActions }
+                            : {}),
+                    },
+                };
+            }
+        }, { operation, argument });
+        if (response.ok && response.value)
+            return response.value;
+        const error = response.error ?? {
+            code: 'runtime-operation-failed',
+            stage: 'control',
+            message: 'Runtime Bridge operation failed.',
+        };
+        throw runtimeError(this.preflight, error.stage === 'game' ? 'game' : 'control', error.message, error.availableActions ? { availableActions: error.availableActions } : undefined, error.code === 'runtime-invalid-state'
+            ? 'runtime-invalid-state'
+            : 'runtime-operation-failed');
+    }
+    assertOperational() {
+        if (this.closed || this.page.isClosed()) {
+            throw runtimeError(this.preflight, 'game', 'The Project browser page is not available.', this.diagnostics(), 'runtime-invalid-state');
+        }
+    }
+    diagnostics() {
+        return {
+            ...this.devServer.diagnostics(),
+            browserErrors: [...this.browserErrors],
+        };
+    }
+    async handleReload() {
+        this.reloading = true;
+        this.browserErrors.length = 0;
+        this.lifecycle.reloading();
+        try {
+            const next = await this.waitForReady();
+            this.readyValue = next;
+            this.lifecycle.reloaded(next);
+        }
+        catch (error) {
+            this.lifecycle.failed(error);
+        }
+        finally {
+            this.reloading = false;
+        }
+    }
+}
+export async function startRuntimeBrowser(preflight, devServer) {
+    let browser;
+    let context;
+    try {
+        browser = await chromium.launch({
+            executablePath: preflight.browserExecutablePath,
+            headless: preflight.headless,
+        });
+        context = await browser.newContext({
+            viewport: preflight.viewport,
+            deviceScaleFactor: 1,
+        });
+        await context.addInitScript(installRuntimeBridgeActivation);
+        const page = await context.newPage();
+        const runtime = new PlaywrightRuntimeBrowser(preflight, devServer, browser, context, page);
+        await runtime.initialize();
+        return runtime;
+    }
+    catch (error) {
+        await context?.close().catch(() => { });
+        await browser?.close().catch(() => { });
+        if (error instanceof RuntimeToolError)
+            throw error;
+        throw runtimeError(preflight, browser ? 'page' : 'browser', `Could not launch a compatible browser context: ${boundedMessage(error)}`, devServer.diagnostics());
+    }
+}