@waica/cli 0.5.0 → 0.6.1

package/dist/mcp/runtime-dev-server.js

@@ -0,0 +1,273 @@
+import { spawn } from 'node:child_process';
+import net from 'node:net';
+import { RuntimeToolError } from './runtime-service.js';
+const TAIL_BYTES = 64 * 1024;
+const LOOPBACK_URL = /http:\/\/127\.0\.0\.1:(\d+)\/?/;
+export const RUNTIME_PORT_PLACEHOLDER = '__WAICA_RUNTIME_PORT__';
+class ByteTail {
+    value = Buffer.alloc(0);
+    append(chunk) {
+        const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        this.value = Buffer.concat([this.value, bytes]).subarray(-TAIL_BYTES);
+    }
+    text() {
+        return this.value.toString('utf8');
+    }
+}
+function delay(milliseconds) {
+    return new Promise((resolve) => setTimeout(resolve, milliseconds));
+}
+async function allocateLoopbackPort() {
+    return new Promise((resolve, reject) => {
+        const server = net.createServer();
+        server.unref();
+        server.once('error', reject);
+        server.listen(0, '127.0.0.1', () => {
+            const address = server.address();
+            if (!address || typeof address === 'string') {
+                server.close();
+                reject(new Error('could not allocate a loopback TCP port'));
+                return;
+            }
+            const { port } = address;
+            server.close((error) => (error ? reject(error) : resolve(port)));
+        });
+    });
+}
+function groupAlive(pid) {
+    try {
+        process.kill(-pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code !== 'ESRCH';
+    }
+}
+function signalGroup(pid, signal) {
+    try {
+        process.kill(-pid, signal);
+    }
+    catch (error) {
+        if (error.code !== 'ESRCH')
+            throw error;
+    }
+}
+async function waitForGroupExit(pid, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() <= deadline) {
+        if (!groupAlive(pid))
+            return true;
+        await delay(10);
+    }
+    return !groupAlive(pid);
+}
+async function terminateGroup(child, graceMs, forceWaitMs) {
+    const pid = child.pid;
+    if (pid === undefined || !groupAlive(pid))
+        return;
+    signalGroup(pid, 'SIGTERM');
+    if (await waitForGroupExit(pid, graceMs))
+        return;
+    signalGroup(pid, 'SIGKILL');
+    if (!(await waitForGroupExit(pid, forceWaitMs))) {
+        throw new Error(`process group ${pid} survived SIGKILL`);
+    }
+}
+async function portAcceptsConnections(url) {
+    const parsed = new URL(url);
+    const port = Number(parsed.port);
+    return new Promise((resolve) => {
+        const socket = net.createConnection({ host: '127.0.0.1', port });
+        const finish = (open) => {
+            socket.destroy();
+            resolve(open);
+        };
+        socket.setTimeout(100);
+        socket.once('connect', () => finish(true));
+        socket.once('timeout', () => finish(false));
+        socket.once('error', () => finish(false));
+    });
+}
+async function waitForClosedPort(url, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() <= deadline) {
+        if (!(await portAcceptsConnections(url)))
+            return true;
+        await delay(10);
+    }
+    return !(await portAcceptsConnections(url));
+}
+async function probe(url) {
+    try {
+        const response = await fetch(url, { signal: AbortSignal.timeout(250) });
+        await response.body?.cancel();
+        return response.ok;
+    }
+    catch {
+        return false;
+    }
+}
+class OwnedRuntimeDevServer {
+    url;
+    child;
+    stdout;
+    stderr;
+    graceMs;
+    forceWaitMs;
+    command;
+    args;
+    stopping = false;
+    stopped = false;
+    exitHandler;
+    constructor(url, child, stdout, stderr, graceMs, forceWaitMs, command, args) {
+        this.url = url;
+        this.child = child;
+        this.stdout = stdout;
+        this.stderr = stderr;
+        this.graceMs = graceMs;
+        this.forceWaitMs = forceWaitMs;
+        this.command = command;
+        this.args = args;
+        child.once('exit', () => {
+            if (!this.stopping)
+                this.exitHandler?.(this.diagnostics());
+        });
+    }
+    setExitHandler(handler) {
+        this.exitHandler = handler;
+    }
+    diagnostics() {
+        return {
+            command: this.command,
+            args: this.args,
+            stdout: this.stdout.text(),
+            stderr: this.stderr.text(),
+            exitCode: this.child.exitCode,
+            signal: this.child.signalCode,
+        };
+    }
+    async stop() {
+        if (this.stopped)
+            return;
+        this.stopping = true;
+        await terminateGroup(this.child, this.graceMs, this.forceWaitMs);
+        if (!(await waitForClosedPort(this.url, this.forceWaitMs))) {
+            throw new Error(`loopback port remained open after process cleanup: ${this.url}`);
+        }
+        this.stopped = true;
+    }
+}
+function diagnostics(child, stdout, stderr, command, args) {
+    return {
+        command,
+        args,
+        stdout: stdout.text(),
+        stderr: stderr.text(),
+        exitCode: child.exitCode,
+        signal: child.signalCode,
+    };
+}
+async function startAttempt(preflight, args, expectedPort, options) {
+    const stdout = new ByteTail();
+    const stderr = new ByteTail();
+    let child;
+    try {
+        child = spawn(preflight.command, args, {
+            cwd: preflight.projectPath,
+            env: { ...process.env, FORCE_COLOR: '0', NO_COLOR: '1' },
+            detached: true,
+            shell: false,
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+    }
+    catch (error) {
+        throw new RuntimeToolError({
+            code: 'runtime-start-failed',
+            stage: 'dev-server',
+            message: `Could not spawn the Project dev script: ${error instanceof Error ? error.message : String(error)}`,
+            projectPath: preflight.projectPath,
+            diagnostics: { command: preflight.command, args, stdout: '', stderr: '' },
+        });
+    }
+    child.stdout?.on('data', (chunk) => stdout.append(chunk));
+    child.stderr?.on('data', (chunk) => stderr.append(chunk));
+    const spawnError = new Promise((resolve) => {
+        child.once('error', (error) => resolve(error));
+        child.once('spawn', () => resolve(null));
+    });
+    const error = await spawnError;
+    if (error) {
+        throw new RuntimeToolError({
+            code: 'runtime-start-failed',
+            stage: 'dev-server',
+            message: `Could not spawn the Project dev script: ${error.message}`,
+            projectPath: preflight.projectPath,
+            diagnostics: { command: preflight.command, args, stdout: stdout.text(), stderr: stderr.text() },
+        });
+    }
+    const deadline = Date.now() + preflight.timeoutMs;
+    let parsedUrl;
+    while (Date.now() <= deadline) {
+        if (child.exitCode !== null || child.signalCode !== null)
+            break;
+        const match = LOOPBACK_URL.exec(`${stdout.text()}\n${stderr.text()}`);
+        if (match) {
+            const reportedPort = Number(match[1]);
+            parsedUrl = `http://127.0.0.1:${reportedPort}/`;
+            if (expectedPort !== undefined && reportedPort !== expectedPort) {
+                await terminateGroup(child, options.graceMs ?? 2_000, options.forceWaitMs ?? 2_000);
+                throw new RuntimeToolError({
+                    code: 'runtime-start-failed',
+                    stage: 'dev-server',
+                    message: `Project dev script did not forward the required --port ${expectedPort}; it reported ${parsedUrl}.`,
+                    projectPath: preflight.projectPath,
+                    diagnostics: diagnostics(child, stdout, stderr, preflight.command, args),
+                });
+            }
+            if (await probe(parsedUrl)) {
+                return new OwnedRuntimeDevServer(parsedUrl, child, stdout, stderr, options.graceMs ?? 2_000, options.forceWaitMs ?? 2_000, preflight.command, args);
+            }
+        }
+        await delay(20);
+    }
+    const detail = diagnostics(child, stdout, stderr, preflight.command, args);
+    await terminateGroup(child, options.graceMs ?? 2_000, options.forceWaitMs ?? 2_000);
+    throw new RuntimeToolError({
+        code: 'runtime-start-failed',
+        stage: 'dev-server',
+        message: child.exitCode !== null
+            ? `Project dev script exited with code ${child.exitCode} before a usable loopback URL was ready.`
+            : parsedUrl
+                ? `Project dev script reported ${parsedUrl}, but its HTTP page never became ready.`
+                : 'Project dev script never reported a usable http://127.0.0.1 URL.',
+        projectPath: preflight.projectPath,
+        diagnostics: detail,
+    });
+}
+function isBindCollision(error) {
+    if (!(error instanceof RuntimeToolError))
+        return false;
+    const diagnosticsText = JSON.stringify(error.body.diagnostics ?? {});
+    return /EADDRINUSE|address already in use|Port \d+ is already in use/i.test(`${error.message}\n${diagnosticsText}`);
+}
+export async function startRuntimeDevServer(preflight, options = {}) {
+    const placeholder = preflight.args.indexOf(RUNTIME_PORT_PLACEHOLDER);
+    if (placeholder === -1)
+        return startAttempt(preflight, preflight.args, undefined, options);
+    const attempts = options.maxPortAttempts ?? 3;
+    let lastError;
+    for (let attempt = 0; attempt < attempts; attempt += 1) {
+        const port = await (options.allocatePort ?? allocateLoopbackPort)();
+        const args = [...preflight.args];
+        args[placeholder] = String(port);
+        try {
+            return await startAttempt(preflight, args, port, options);
+        }
+        catch (error) {
+            lastError = error;
+            if (!isBindCollision(error) || attempt === attempts - 1)
+                throw error;
+        }
+    }
+    throw lastError;
+}

package/dist/mcp/runtime-preflight.js

@@ -0,0 +1,249 @@
+import { constants } from 'node:fs';
+import { access, readFile, realpath } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { RuntimeToolError, } from './runtime-service.js';
+const RUNTIME_PORT_ARGUMENT = '__WAICA_RUNTIME_PORT__';
+function runtimeError(projectPath, stage, message) {
+    return new RuntimeToolError({
+        code: 'runtime-prerequisite-missing',
+        stage,
+        message,
+        projectPath,
+    });
+}
+async function exists(file) {
+    try {
+        await access(file);
+        return true;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return false;
+        throw error;
+    }
+}
+async function defaultCommandAvailable(command) {
+    return new Promise((resolve) => {
+        const child = spawn(command, ['--version'], { stdio: 'ignore' });
+        child.once('error', (error) => {
+            if (error.code === 'ENOENT')
+                resolve(false);
+            else
+                resolve(false);
+        });
+        child.once('spawn', () => {
+            child.once('close', () => resolve(true));
+        });
+    });
+}
+const MAC_BROWSERS = [
+    '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+    '/Applications/Chromium.app/Contents/MacOS/Chromium',
+];
+const LINUX_BROWSERS = [
+    '/usr/bin/google-chrome',
+    '/usr/bin/google-chrome-stable',
+    '/usr/bin/chromium',
+    '/usr/bin/chromium-browser',
+];
+async function defaultDiscoverBrowser(explicitPath) {
+    const candidates = explicitPath
+        ? [explicitPath]
+        : process.platform === 'darwin'
+            ? MAC_BROWSERS
+            : LINUX_BROWSERS;
+    for (const candidate of candidates) {
+        try {
+            await access(candidate, constants.X_OK);
+            return realpath(candidate);
+        }
+        catch {
+            // Continue deterministic discovery.
+        }
+    }
+    return undefined;
+}
+export const DEFAULT_RUNTIME_PREFLIGHT_ADAPTERS = {
+    platform: process.platform,
+    commandAvailable: defaultCommandAvailable,
+    discoverBrowser: defaultDiscoverBrowser,
+};
+function isPositiveInteger(value) {
+    return typeof value === 'number' && Number.isInteger(value) && value > 0;
+}
+function validateViewport(projectPath, value, label) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return null;
+    const { width, height } = value;
+    if (!isPositiveInteger(width) || !isPositiveInteger(height) || width * height > 1_000_000) {
+        if (label === 'explicit') {
+            throw runtimeError(projectPath, 'project', 'viewport width and height must be positive integers totaling at most 1,000,000 pixels.');
+        }
+        return null;
+    }
+    return { width, height };
+}
+async function projectViewport(projectPath, explicit) {
+    if (explicit)
+        return validateViewport(projectPath, explicit, 'explicit');
+    try {
+        const game = JSON.parse(await readFile(path.join(projectPath, 'src/game.json'), 'utf8'));
+        return validateViewport(projectPath, game.resolution, 'project') ?? { width: 640, height: 360 };
+    }
+    catch {
+        return { width: 640, height: 360 };
+    }
+}
+async function selectPackageManager(projectPath, manifest) {
+    if (manifest.packageManager !== undefined) {
+        if (typeof manifest.packageManager !== 'string') {
+            throw runtimeError(projectPath, 'package-manager', 'packageManager must be a string such as pnpm@11.4.0.');
+        }
+        const match = /^(npm|pnpm|yarn|bun)@[^\s]+$/.exec(manifest.packageManager);
+        if (!match) {
+            throw runtimeError(projectPath, 'package-manager', `Unsupported or invalid packageManager "${manifest.packageManager}"; use npm, pnpm, yarn or bun with a version.`);
+        }
+        return match[1];
+    }
+    const locks = [
+        ['package-lock.json', 'npm'],
+        ['pnpm-lock.yaml', 'pnpm'],
+        ['yarn.lock', 'yarn'],
+        ['bun.lock', 'bun'],
+        ['bun.lockb', 'bun'],
+    ];
+    const present = [];
+    for (const lock of locks) {
+        if (await exists(path.join(projectPath, lock[0])))
+            present.push(lock);
+    }
+    if (present.length > 1) {
+        throw runtimeError(projectPath, 'package-manager', `Conflicting root lockfiles: ${present.map(([file]) => file).join(', ')}. Keep exactly one.`);
+    }
+    return present[0]?.[1] ?? 'npm';
+}
+function devArgs(manager) {
+    const viteArgs = [
+        '--host',
+        '127.0.0.1',
+        '--port',
+        RUNTIME_PORT_ARGUMENT,
+        '--strictPort',
+    ];
+    return manager === 'yarn'
+        ? ['run', 'dev', ...viteArgs]
+        : ['run', 'dev', '--', ...viteArgs];
+}
+async function packageRootFromEntry(entry, packageName) {
+    for (let current = path.dirname(entry);; current = path.dirname(current)) {
+        try {
+            const manifest = JSON.parse(await readFile(path.join(current, 'package.json'), 'utf8'));
+            if (manifest.name === packageName)
+                return current;
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        const parent = path.dirname(current);
+        if (parent === current)
+            throw new Error(`could not locate package root for ${packageName}`);
+    }
+}
+async function verifyDependencies(projectPath, manifest) {
+    const dependencies = {
+        ...(manifest.dependencies ?? {}),
+        ...(manifest.devDependencies ?? {}),
+    };
+    const names = Object.keys(dependencies).sort();
+    if (!names.includes('@waica/engine')) {
+        throw runtimeError(projectPath, 'dependencies', 'The Project must declare and install @waica/engine before it can run.');
+    }
+    const anchoredRequire = createRequire(path.join(projectPath, 'package.json'));
+    const entries = new Map();
+    for (const name of names) {
+        try {
+            entries.set(name, anchoredRequire.resolve(name));
+        }
+        catch (error) {
+            throw runtimeError(projectPath, 'dependencies', `Project dependency ${name} is not resolvable; install dependencies before starting. (${error instanceof Error ? error.message : String(error)})`);
+        }
+    }
+    const engineRoot = await packageRootFromEntry(entries.get('@waica/engine'), '@waica/engine');
+    const engineManifest = JSON.parse(await readFile(path.join(engineRoot, 'package.json'), 'utf8'));
+    if (typeof engineManifest.version !== 'string' || engineManifest.version.length === 0) {
+        throw runtimeError(projectPath, 'dependencies', 'Installed @waica/engine has no valid version.');
+    }
+    return { package: '@waica/engine', version: engineManifest.version, source: 'project' };
+}
+export async function preflightRuntimeProject(input, adapters = DEFAULT_RUNTIME_PREFLIGHT_ADAPTERS) {
+    if (adapters.platform === 'win32') {
+        throw new RuntimeToolError({
+            code: 'runtime-unsupported-host',
+            stage: 'project',
+            message: 'Run Sessions support macOS and Linux; Windows is not supported in this MVP.',
+            projectPath: input.projectPath,
+        });
+    }
+    if (adapters.platform !== 'darwin' && adapters.platform !== 'linux') {
+        throw new RuntimeToolError({
+            code: 'runtime-unsupported-host',
+            stage: 'project',
+            message: `Run Sessions do not support host platform ${adapters.platform}.`,
+            projectPath: input.projectPath,
+        });
+    }
+    let projectPath;
+    try {
+        projectPath = await realpath(input.projectPath);
+    }
+    catch (error) {
+        throw runtimeError(input.projectPath, 'project', `Project path is not accessible: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (!(await exists(path.join(projectPath, 'src/game.json'))) &&
+        !(await exists(path.join(projectPath, 'src/scenes/main.scene.json')))) {
+        throw runtimeError(projectPath, 'project', 'Not a Waica Project: expected src/game.json or src/scenes/main.scene.json.');
+    }
+    let manifest;
+    try {
+        const parsed = JSON.parse(await readFile(path.join(projectPath, 'package.json'), 'utf8'));
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+            throw new Error('expected an object');
+        manifest = parsed;
+    }
+    catch (error) {
+        throw runtimeError(projectPath, 'project', `package.json must be readable JSON: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const dev = manifest.scripts?.dev;
+    if (typeof dev !== 'string' || dev.trim().length === 0) {
+        throw runtimeError(projectPath, 'project', 'package.json scripts.dev must be a nonempty string.');
+    }
+    const packageManager = await selectPackageManager(projectPath, manifest);
+    if (!(await adapters.commandAvailable(packageManager))) {
+        throw runtimeError(projectPath, 'package-manager', `Package-manager executable "${packageManager}" is not available on PATH.`);
+    }
+    const engine = await verifyDependencies(projectPath, manifest);
+    const browserExecutablePath = await adapters.discoverBrowser(input.browserExecutablePath);
+    if (!browserExecutablePath) {
+        throw runtimeError(projectPath, 'browser', input.browserExecutablePath
+            ? `Browser executable is not available: ${input.browserExecutablePath}`
+            : 'No compatible system Chrome or Chromium executable was found.');
+    }
+    const timeoutMs = input.timeoutMs ?? 30_000;
+    if (!Number.isInteger(timeoutMs) || timeoutMs < 1_000 || timeoutMs > 120_000) {
+        throw runtimeError(projectPath, 'project', 'timeout_ms must be an integer from 1,000 through 120,000.');
+    }
+    return {
+        projectPath,
+        packageManager,
+        command: packageManager,
+        args: devArgs(packageManager),
+        viewport: await projectViewport(projectPath, input.viewport),
+        timeoutMs,
+        headless: input.headless ?? true,
+        browserExecutablePath,
+        engine,
+    };
+}

package/dist/mcp/runtime-service.js

@@ -0,0 +1,8 @@
+export class RuntimeToolError extends Error {
+    body;
+    constructor(body) {
+        super(body.message);
+        this.body = body;
+        this.name = 'RuntimeToolError';
+    }
+}