pixifact-cli 0.4.0 → 0.6.0

package/src/pixifact-cli.ts

@@ -1,9 +1,14 @@
 #!/usr/bin/env bun
+import fs from 'node:fs';
+import path from 'node:path';
 import { createPixifactAutomation } from './automation';
 import { hintForCommandError } from 'pixifact';
 import { CompileSceneError, compileScenes } from 'pixifact/compiler-node';
 import type { SceneValidationDiagnostic } from 'pixifact/compiler';
-import { createLiveBridgeServer } from './liveBridgeServer';
+import { startEditorServer } from './editorServer';
+import { captureEditorScreenshot, queryEditorContext } from './editorSession';
+import { queryRuntime, queryRuntimeList } from './runtimeSession';
+import type { RuntimeLogLevel, RuntimeRequest } from 'pixifact/runtime-dev';
 import {
     buildWechatTarget,
     devWechatTarget,
@@ -13,14 +18,15 @@ import {
 } from './wechatTarget';
 
 type Automation = ReturnType<typeof createPixifactAutomation>;
-type LiveBridge = Pick<ReturnType<typeof createLiveBridgeServer>, 'connected' | 'callAction' | 'stop'> & {
-    waitForConnection?: (timeoutMs?: number) => Promise<void>;
-};
 
 interface CliOptions {
     automation?: Automation;
-    liveBridge?: LiveBridge;
+    captureEditorScreenshot?: typeof captureEditorScreenshot;
     onWechatDevEvent?: (event: WechatDevEvent) => void;
+    readEditorContext?: typeof queryEditorContext;
+    listRuntimes?: typeof queryRuntimeList;
+    queryRuntime?: typeof queryRuntime;
+    startEditor?: typeof startEditorServer;
 }
 
 interface CliResult {
@@ -83,6 +89,23 @@ function projectRootFlag(flags: Record<string, string | true>) {
     return requireFlag(flags, 'project-root');
 }
 
+function optionalFlag(flags: Record<string, string | true>, name: string) {
+    const value = flags[name];
+    return value === undefined ? undefined : requireFlag(flags, name);
+}
+
+function finiteNumberFlag(flags: Record<string, string | true>, name: string) {
+    const value = Number(requireFlag(flags, name));
+    if (!Number.isFinite(value)) throw new Error(`--${name} must be a finite number.`);
+    return value;
+}
+
+function nonNegativeInteger(value: string | undefined, error: string) {
+    const number = Number(value);
+    if (!Number.isInteger(number) || number < 0) throw new Error(error);
+    return number;
+}
+
 function jsonLine(value: unknown) {
     return `${JSON.stringify(value, null, 2)}\n`;
 }
@@ -93,9 +116,25 @@ function isFailedResult(value: unknown): value is CliJsonResult {
         && (value as CliJsonResult).ok === false;
 }
 
+function isRuntimeTreeResult(value: unknown): value is { runtimeId: string; root: unknown } {
+    return typeof value === 'object'
+        && value !== null
+        && typeof (value as { runtimeId?: unknown }).runtimeId === 'string'
+        && 'root' in value;
+}
+
 function compileScenesFailure(error: unknown): CliJsonResult {
     const message = error instanceof Error ? error.message : String(error);
     if (error instanceof CompileSceneError) {
+        if (error.diagnostics) {
+            return {
+                ok: false,
+                scene: error.scene,
+                error: 'Scene compile failed.',
+                diagnostics: error.diagnostics,
+                hint: 'Fix the listed diagnostics, then run compile-scenes again.',
+            };
+        }
         const sourceDiagnostic = sourceDiagnosticFromMessage(error.source ?? '', message);
         if (sourceDiagnostic) {
             return {
@@ -218,10 +257,119 @@ async function executeFileCommand(
     flags: Record<string, string | true>,
     automation: Automation,
     onWechatDevEvent?: (event: WechatDevEvent) => void,
+    startEditor: typeof startEditorServer = startEditorServer,
+    readEditorContext: typeof queryEditorContext = queryEditorContext,
+    captureScreenshot: typeof captureEditorScreenshot = captureEditorScreenshot,
+    listRuntimes: typeof queryRuntimeList = queryRuntimeList,
+    sendRuntimeRequest: typeof queryRuntime = queryRuntime,
 ) {
     const [area, action] = positionals;
     const projectRoot = projectRootFlag(flags);
 
+    if (area === 'runtime' && action === 'list') {
+        return listRuntimes({ projectRoot });
+    }
+
+    if (area === 'runtime' && action !== undefined) {
+        const runtimeId = optionalFlag(flags, 'runtime');
+        let request: RuntimeRequest;
+        if (action === 'tree') {
+            request = { type: 'tree' };
+        } else if (action === 'node') {
+            request = {
+                type: 'node',
+                uid: nonNegativeInteger(
+                    positionals[2],
+                    'Runtime node uid must be a non-negative integer.',
+                ),
+            };
+        } else if (action === 'state') {
+            request = { type: 'state' };
+        } else if (action === 'logs') {
+            const after = flags.after === undefined
+                ? undefined
+                : nonNegativeInteger(requireFlag(flags, 'after'), '--after must be a non-negative integer.');
+            const level = optionalFlag(flags, 'level');
+            if (level && !['debug', 'log', 'info', 'warn', 'error'].includes(level)) {
+                throw new Error('--level must be debug, log, info, warn, or error.');
+            }
+            request = {
+                type: 'logs',
+                ...(after === undefined ? {} : { after }),
+                ...(level === undefined ? {} : { level: level as RuntimeLogLevel }),
+            };
+        } else if (action === 'input') {
+            const inputAction = positionals[2];
+            if (inputAction === 'click' || inputAction === 'move') {
+                request = {
+                    type: 'input',
+                    action: inputAction,
+                    x: finiteNumberFlag(flags, 'x'),
+                    y: finiteNumberFlag(flags, 'y'),
+                };
+            } else if (inputAction === 'key' || inputAction === 'keydown' || inputAction === 'keyup') {
+                const key = positionals[3];
+                if (!key) throw new Error(`runtime input ${inputAction} requires a key.`);
+                request = { type: 'input', action: inputAction, key };
+            } else {
+                throw new Error(`Unknown Pixifact Runtime input "${inputAction ?? ''}".`);
+            }
+        } else {
+            throw new Error(`Unknown Pixifact CLI command "${positionals.join(' ')}".`);
+        }
+        const result = await sendRuntimeRequest({ projectRoot, runtimeId, request });
+        if (action !== 'tree' || flags.output === undefined || isFailedResult(result)) {
+            return result;
+        }
+        if (!isRuntimeTreeResult(result)) {
+            throw new Error('Pixifact Runtime returned an invalid tree response.');
+        }
+        const output = path.resolve(requireFlag(flags, 'output'));
+        const capturedAt = new Date().toISOString();
+        fs.mkdirSync(path.dirname(output), { recursive: true });
+        fs.writeFileSync(output, jsonLine({
+            schemaVersion: 1,
+            capturedAt,
+            runtimeId: result.runtimeId,
+            root: result.root,
+        }), 'utf8');
+        return {
+            ok: true,
+            output,
+            runtimeId: result.runtimeId,
+            capturedAt,
+        };
+    }
+
+    if (area === 'editor' && action === undefined) {
+        const session = await startEditor({ projectRoot });
+        return {
+            ok: true,
+            projectRoot,
+            url: session.url,
+        };
+    }
+
+    if (area === 'editor' && action === 'context') {
+        return readEditorContext({ projectRoot });
+    }
+
+    if (area === 'editor' && action === 'screenshot') {
+        const output = path.resolve(requireFlag(flags, 'output'));
+        const screenshot = await captureScreenshot({ projectRoot });
+        if (!screenshot.ok) return screenshot;
+        fs.writeFileSync(output, screenshot.data);
+        return {
+            ok: true,
+            scene: screenshot.scene,
+            revision: screenshot.revision,
+            width: screenshot.width,
+            height: screenshot.height,
+            bytes: screenshot.data.byteLength,
+            output,
+        };
+    }
+
     if ((area === 'build' || area === 'dev' || area === 'validate') && action === undefined) {
         const target = requireFlag(flags, 'target');
         if (target !== 'wechat') {
@@ -350,32 +498,7 @@ async function executeFileCommand(
     throw new Error(`Unknown Pixifact CLI command "${positionals.join(' ')}".`);
 }
 
-async function executeLiveCommand(positionals: string[], flags: Record<string, string | true>, bridge: LiveBridge) {
-    if (!bridge.connected && bridge.waitForConnection) {
-        await bridge.waitForConnection();
-    }
-    if (!bridge.connected) {
-        throw new Error('No live Pixifact editor is connected.');
-    }
-
-    const [area, action] = positionals;
-    if (area === 'summary' && action === undefined) {
-        return bridge.callAction('summary', {});
-    }
-    if (area === 'scene' && action === 'get') {
-        return bridge.callAction('scene.get', {});
-    }
-    if (area === 'node' && action === 'inspect') {
-        return bridge.callAction('node.inspect', {
-            node: requireFlag(flags, 'node'),
-        });
-    }
-
-    throw new Error(`Unknown Pixifact live command "${positionals.join(' ')}".`);
-}
-
 export async function executePixifactCli(argv: string[], options: CliOptions = {}): Promise<CliResult> {
-    let ownedBridge: ReturnType<typeof createLiveBridgeServer> | undefined;
     try {
         const parsed = parseArgs(argv);
         if (parsed.flags.help === true) {
@@ -394,15 +517,26 @@ export async function executePixifactCli(argv: string[], options: CliOptions = {
                     aiValidationAlternatives: [
                         'scene validate --all',
                     ],
+                    runtimeCommands: [
+                        'runtime list',
+                        'runtime tree [--output <json-path>] [--runtime <runtime-id>]',
+                        'runtime node <pixi-uid> [--runtime <runtime-id>]',
+                        'runtime state [--runtime <runtime-id>]',
+                        'runtime logs [--after <seq>] [--level <level>] [--runtime <runtime-id>]',
+                        'runtime input click --x <x> --y <y> [--runtime <runtime-id>]',
+                        'runtime input move --x <x> --y <y> [--runtime <runtime-id>]',
+                        'runtime input key <key> [--runtime <runtime-id>]',
+                        'runtime input keydown <key> [--runtime <runtime-id>]',
+                        'runtime input keyup <key> [--runtime <runtime-id>]',
+                    ],
                     auxiliaryCommands: [
+                        'editor',
+                        'editor context',
+                        'editor screenshot --output <png-path>',
                         'scene create --scene <scene-path> --name <SceneName>',
                         'node inspect --scene <scene-path> --node <locator>',
                     ],
-                    liveContextCommands: [
-                        'live summary',
-                        'live scene get',
-                        'live node inspect --node <locator>',
-                    ],
+                    nodeLocatorSource: 'scene inspect --scene <scene-path> returns node locator values',
                     defaults: {
                         projectRoot: 'current working directory',
                     },
@@ -412,19 +546,17 @@ export async function executePixifactCli(argv: string[], options: CliOptions = {
         }
 
         const automation = options.automation ?? createPixifactAutomation();
-        const isLive = parsed.positionals[0] === 'live';
-        const result = isLive
-            ? await executeLiveCommand(
-                parsed.positionals.slice(1),
-                parsed.flags,
-                options.liveBridge ?? (ownedBridge = createLiveBridgeServer()),
-            )
-            : await executeFileCommand(
-                parsed.positionals,
-                parsed.flags,
-                automation,
-                options.onWechatDevEvent,
-            );
+        const result = await executeFileCommand(
+            parsed.positionals,
+            parsed.flags,
+            automation,
+            options.onWechatDevEvent,
+            options.startEditor,
+            options.readEditorContext,
+            options.captureEditorScreenshot,
+            options.listRuntimes,
+            options.queryRuntime,
+        );
         if (isFailedResult(result)) {
             return {
                 exitCode: 1,
@@ -447,8 +579,6 @@ export async function executePixifactCli(argv: string[], options: CliOptions = {
                 hint: hintForCommandError(error instanceof Error ? error.message : String(error)),
             }),
         };
-    } finally {
-        ownedBridge?.stop();
     }
 }
 

package/src/runtimeSession.ts

@@ -0,0 +1,133 @@
+import {
+    findActiveRuntimeSession,
+    type RuntimeSessionDescriptor,
+} from 'pixifact/compiler-node';
+import type { RuntimePageDescriptor, RuntimeRequest } from 'pixifact/runtime-dev';
+
+interface RuntimeSessionLookupOptions {
+    projectRoot: string;
+    sessionsRoot?: string;
+    fetch?: typeof fetch;
+}
+
+interface RuntimeQueryOptions extends RuntimeSessionLookupOptions {
+    runtimeId?: string;
+    request: RuntimeRequest;
+}
+
+type RuntimeListResult =
+    | { ok: true; runtimes: Array<RuntimePageDescriptor & { connectedAt: string }> }
+    | { ok: false; error: string; [key: string]: unknown };
+
+async function activeDescriptor(options: RuntimeSessionLookupOptions) {
+    const descriptor = await findActiveRuntimeSession(options);
+    if (!descriptor) {
+        return {
+            ok: false as const,
+            error: 'No Pixifact Runtime Vite server is running for this project.',
+        };
+    }
+    return { ok: true as const, descriptor };
+}
+
+async function runtimeHostFetch(
+    descriptor: RuntimeSessionDescriptor,
+    pathname: string,
+    fetcher: typeof fetch,
+    init: RequestInit = {},
+) {
+    try {
+        const response = await fetcher(`${descriptor.origin}/__pixifact_runtime__/${pathname}`, {
+            ...init,
+            headers: {
+                authorization: `Bearer ${descriptor.token}`,
+                ...init.headers,
+            },
+        });
+        return await response.json() as Record<string, unknown>;
+    } catch {
+        return {
+            ok: false,
+            error: 'Pixifact Runtime Vite server is not reachable for this project.',
+        };
+    }
+}
+
+export async function queryRuntimeList(
+    options: RuntimeSessionLookupOptions,
+): Promise<RuntimeListResult> {
+    const active = await activeDescriptor(options);
+    if (!active.ok) return active;
+    const result = await runtimeHostFetch(active.descriptor, 'list', options.fetch ?? fetch);
+    if (
+        result.ok !== true
+        || !Array.isArray(result.runtimes)
+        || !result.runtimes.every((runtime) => (
+            typeof runtime === 'object'
+            && runtime !== null
+            && typeof runtime.runtimeId === 'string'
+            && typeof runtime.url === 'string'
+            && typeof runtime.title === 'string'
+            && typeof runtime.ready === 'boolean'
+            && typeof runtime.connectedAt === 'string'
+        ))
+    ) {
+        return result.ok === false && typeof result.error === 'string'
+            ? result as RuntimeListResult
+            : {
+                ok: false,
+                error: 'Pixifact Runtime Vite server returned an invalid runtime list.',
+            };
+    }
+    return result as RuntimeListResult;
+}
+
+function selectRuntime(
+    runtimes: Array<RuntimePageDescriptor & { connectedAt: string }>,
+    runtimeId: string | undefined,
+) {
+    if (runtimeId) {
+        const selected = runtimes.find((runtime) => runtime.runtimeId === runtimeId);
+        return selected
+            ? { ok: true as const, runtime: selected }
+            : {
+                ok: false as const,
+                error: `Pixifact Runtime "${runtimeId}" is not connected.`,
+                runtimes,
+            };
+    }
+    if (runtimes.length === 0) {
+        return {
+            ok: false as const,
+            error: 'No Pixifact Runtime game page is connected for this project.',
+        };
+    }
+    if (runtimes.length > 1) {
+        return {
+            ok: false as const,
+            error: 'Multiple Pixifact Runtime game pages are connected. Use --runtime <runtime-id>.',
+            runtimes,
+        };
+    }
+    return { ok: true as const, runtime: runtimes[0] };
+}
+
+export async function queryRuntime(options: RuntimeQueryOptions) {
+    const active = await activeDescriptor(options);
+    if (!active.ok) return active;
+    const listed = await runtimeHostFetch(active.descriptor, 'list', options.fetch ?? fetch);
+    if (listed.ok !== true || !Array.isArray(listed.runtimes)) return listed;
+    const selected = selectRuntime(
+        listed.runtimes as Array<RuntimePageDescriptor & { connectedAt: string }>,
+        options.runtimeId,
+    );
+    if (!selected.ok) return selected;
+    return runtimeHostFetch(active.descriptor, 'request', options.fetch ?? fetch, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({
+            runtimeId: selected.runtime.runtimeId,
+            request: options.request,
+        }),
+    });
+}

package/src/liveBridge.ts

@@ -1,28 +0,0 @@
-export const pixifactAgentBridgePort = 8791;
-export const pixifactAgentBridgePath = '/pixifact-agent';
-export const pixifactAgentBridgeUrl = `ws://127.0.0.1:${pixifactAgentBridgePort}${pixifactAgentBridgePath}`;
-
-export type LiveBridgeRole = 'editor';
-
-export interface LiveBridgeHelloMessage {
-    type: 'hello';
-    role: LiveBridgeRole;
-}
-
-export interface LiveBridgeRequestMessage {
-    type: 'request';
-    id: string;
-    action: string;
-    arguments: unknown;
-}
-
-export interface LiveBridgeResponseMessage {
-    type: 'response';
-    id: string;
-    ok: boolean;
-    result?: unknown;
-    error?: string;
-}
-
-export type LiveBridgeClientMessage = LiveBridgeHelloMessage | LiveBridgeResponseMessage;
-export type LiveBridgeServerMessage = LiveBridgeRequestMessage;

package/src/liveBridgeServer.ts

@@ -1,163 +0,0 @@
-import {
-    pixifactAgentBridgePath,
-    pixifactAgentBridgePort,
-    type LiveBridgeClientMessage,
-    type LiveBridgeRequestMessage,
-    type LiveBridgeResponseMessage,
-} from './liveBridge';
-
-interface BunServerSocket {
-    send(data: string): void;
-}
-
-interface BunServer {
-    upgrade(request: Request): boolean;
-    stop(force?: boolean): void;
-}
-
-interface BunServeOptions {
-    hostname: string;
-    port: number;
-    fetch(request: Request, server: BunServer): Response | undefined;
-    websocket: {
-        message(socket: BunServerSocket, data: string | Uint8Array): void;
-        close(socket: BunServerSocket): void;
-    };
-}
-
-declare const Bun: {
-    serve(options: BunServeOptions): BunServer;
-};
-
-interface PendingRequest {
-    resolve(result: unknown): void;
-    reject(error: Error): void;
-    timer: ReturnType<typeof setTimeout>;
-}
-
-interface LiveBridgeServerOptions {
-    port?: number;
-    requestTimeoutMs?: number;
-}
-
-function responseError(message: LiveBridgeResponseMessage) {
-    return new Error(message.error ?? 'Live editor request failed.');
-}
-
-export function createLiveBridgeServer(options: LiveBridgeServerOptions = {}) {
-    const port = options.port ?? pixifactAgentBridgePort;
-    const requestTimeoutMs = options.requestTimeoutMs ?? 30000;
-    let editor: BunServerSocket | undefined;
-    const pending = new Map<string, PendingRequest>();
-    const connectionWaiters = new Set<() => void>();
-    let nextRequestId = 0;
-
-    function rejectPending(error: Error) {
-        for (const pendingRequest of pending.values()) {
-            clearTimeout(pendingRequest.timer);
-            pendingRequest.reject(error);
-        }
-        pending.clear();
-    }
-
-    const server = Bun.serve({
-        hostname: '127.0.0.1',
-        port,
-        fetch(request, server) {
-            const url = new URL(request.url);
-            if (url.pathname !== pixifactAgentBridgePath) {
-                return new Response('Not found.', { status: 404 });
-            }
-            if (server.upgrade(request)) {
-                return undefined;
-            }
-            return new Response('WebSocket upgrade failed.', { status: 400 });
-        },
-        websocket: {
-            message(socket, data) {
-                const message = JSON.parse(String(data)) as LiveBridgeClientMessage;
-                if (message.type === 'hello' && message.role === 'editor') {
-                    editor = socket;
-                    for (const resolve of connectionWaiters) {
-                        resolve();
-                    }
-                    connectionWaiters.clear();
-                    return;
-                }
-                if (message.type !== 'response') {
-                    return;
-                }
-                const pendingRequest = pending.get(message.id);
-                if (!pendingRequest) {
-                    return;
-                }
-                pending.delete(message.id);
-                clearTimeout(pendingRequest.timer);
-                if (message.ok) {
-                    pendingRequest.resolve(message.result);
-                } else {
-                    pendingRequest.reject(responseError(message));
-                }
-            },
-            close(socket) {
-                if (socket === editor) {
-                    editor = undefined;
-                    rejectPending(new Error('Live editor disconnected.'));
-                }
-            },
-        },
-    });
-
-    return {
-        get connected() {
-            return editor !== undefined;
-        },
-
-        async waitForConnection(timeoutMs = 3000) {
-            if (editor) {
-                return;
-            }
-            return new Promise<void>((resolve, reject) => {
-                const timer = setTimeout(() => {
-                    connectionWaiters.delete(done);
-                    reject(new Error('No live Pixifact editor is connected.'));
-                }, timeoutMs);
-                function done() {
-                    clearTimeout(timer);
-                    resolve();
-                }
-                connectionWaiters.add(done);
-            });
-        },
-
-        async callAction(action: string, args: unknown) {
-            if (!editor) {
-                throw new Error('No live Pixifact editor is connected.');
-            }
-            const id = `live-${Date.now()}-${nextRequestId++}`;
-            const message: LiveBridgeRequestMessage = {
-                type: 'request',
-                id,
-                action,
-                arguments: args,
-            };
-            return new Promise((resolve, reject) => {
-                const timer = setTimeout(() => {
-                    pending.delete(id);
-                    reject(new Error(`Live editor action "${action}" timed out.`));
-                }, requestTimeoutMs);
-                pending.set(id, {
-                    resolve,
-                    reject,
-                    timer,
-                });
-                editor!.send(JSON.stringify(message));
-            });
-        },
-
-        stop() {
-            rejectPending(new Error('Live bridge stopped.'));
-            server.stop(true);
-        },
-    };
-}