@go-go-golems/os-scripting 0.1.0

package/repl/jsReplDriver.js

@@ -0,0 +1,348 @@
+import { getAttachedJsSession, listAttachedJsSessions } from './attachedJsSessionRegistry';
+import { createJsSessionBroker } from './jsSessionBroker';
+const JS_KEYWORDS = [
+    'await',
+    'break',
+    'const',
+    'continue',
+    'else',
+    'false',
+    'for',
+    'function',
+    'if',
+    'let',
+    'null',
+    'return',
+    'switch',
+    'throw',
+    'true',
+    'typeof',
+    'undefined',
+    'var',
+    'while',
+];
+const COMMAND_HELP = {
+    ':spawn': {
+        title: ':spawn',
+        detail: 'Spawn a blank JavaScript session.',
+        usage: ':spawn [session-id]',
+    },
+    ':sessions': {
+        title: ':sessions',
+        detail: 'List live JavaScript sessions, including attached runtime-backed sessions.',
+        usage: ':sessions',
+    },
+    ':attach': {
+        title: ':attach',
+        detail: 'Attach to a live runtime-backed JavaScript session.',
+        usage: ':attach <session-id>',
+    },
+    ':use': {
+        title: ':use',
+        detail: 'Select the active JavaScript session for plain eval lines.',
+        usage: ':use <session-id>',
+    },
+    ':globals': {
+        title: ':globals',
+        detail: 'List globals in the active or provided session.',
+        usage: ':globals [session-id]',
+    },
+    ':reset': {
+        title: ':reset',
+        detail: 'Reset the active or provided session back to its initial prelude.',
+        usage: ':reset [session-id]',
+    },
+    ':dispose': {
+        title: ':dispose',
+        detail: 'Dispose a JavaScript session.',
+        usage: ':dispose [session-id]',
+    },
+    ':help': {
+        title: ':help',
+        detail: 'Show JS REPL command help.',
+        usage: ':help [topic]',
+    },
+};
+function splitCommand(raw) {
+    const trimmed = raw.trim();
+    const spaceIndex = trimmed.indexOf(' ');
+    if (spaceIndex === -1) {
+        return { command: trimmed, rest: '' };
+    }
+    return {
+        command: trimmed.slice(0, spaceIndex),
+        rest: trimmed.slice(spaceIndex + 1).trim(),
+    };
+}
+function nextGeneratedSessionId(counter) {
+    return `js-${counter}`;
+}
+function formatValue(value) {
+    if (typeof value === 'string') {
+        return value;
+    }
+    if (value === undefined) {
+        return 'undefined';
+    }
+    if (value === null) {
+        return 'null';
+    }
+    if (typeof value === 'number' || typeof value === 'boolean' || typeof value === 'bigint') {
+        return String(value);
+    }
+    try {
+        return JSON.stringify(value, null, 2);
+    }
+    catch {
+        return String(value);
+    }
+}
+function formatEvalLines(result) {
+    const lines = result.logs.map((text) => ({ type: 'system', text }));
+    if (result.error) {
+        lines.push({
+            type: 'error',
+            text: `${result.error.name}: ${result.error.message}`,
+        });
+        return lines;
+    }
+    lines.push({
+        type: 'output',
+        text: formatValue(result.value),
+    });
+    return lines;
+}
+function currentToken(input) {
+    const match = input.match(/([A-Za-z_$:][\w$:]*)$/);
+    return match?.[1] ?? '';
+}
+function promptForSession(sessionId, origin) {
+    if (!sessionId || !origin) {
+        return 'js>';
+    }
+    return origin === 'attached-runtime' ? `js[runtime:${sessionId}]>` : `js[${sessionId}]>`;
+}
+export function createJsReplDriver(options = {}) {
+    const broker = options.broker ?? createJsSessionBroker();
+    let activeSessionId = options.initialSessionId ?? null;
+    let activeOrigin = options.initialOrigin ?? null;
+    let sessionCounter = 1;
+    function requireSession(sessionIdArg) {
+        const sessionId = sessionIdArg ?? activeSessionId;
+        if (!sessionId) {
+            throw new Error('No active JS session. Use :spawn or :use <session-id> first.');
+        }
+        const spawned = broker.getSession(sessionId);
+        if (spawned) {
+            return {
+                kind: 'spawned',
+                sessionId,
+                title: broker.listSessions().find((summary) => summary.sessionId === sessionId)?.title ?? sessionId,
+                origin: 'spawned',
+                session: spawned,
+            };
+        }
+        const attached = getAttachedJsSession(sessionId);
+        if (attached) {
+            return {
+                kind: 'attached-runtime',
+                sessionId,
+                title: attached.summary.title,
+                origin: 'attached-runtime',
+                session: attached.handle,
+            };
+        }
+        throw new Error(`Unknown JS session: ${sessionId}`);
+    }
+    return {
+        async execute(raw, _context) {
+            const trimmed = raw.trim();
+            if (!trimmed) {
+                return { lines: [] };
+            }
+            if (trimmed.startsWith(':')) {
+                const { command, rest } = splitCommand(trimmed);
+                switch (command) {
+                    case ':spawn': {
+                        const sessionId = rest || nextGeneratedSessionId(sessionCounter++);
+                        await broker.spawnSession({ sessionId, title: `JavaScript ${sessionId}` });
+                        activeSessionId = sessionId;
+                        activeOrigin = 'spawned';
+                        return {
+                            lines: [
+                                { type: 'system', text: `Spawned JS session ${sessionId}` },
+                            ],
+                            envVars: {
+                                REPL_PROMPT: promptForSession(sessionId, 'spawned'),
+                            },
+                        };
+                    }
+                    case ':sessions': {
+                        const sessions = [
+                            ...broker.listSessions().map((summary) => ({
+                                sessionId: summary.sessionId,
+                                title: summary.title,
+                                origin: 'spawned',
+                            })),
+                            ...listAttachedJsSessions().map((entry) => ({
+                                sessionId: entry.summary.sessionId,
+                                title: entry.summary.title,
+                                origin: 'attached-runtime',
+                            })),
+                        ].sort((left, right) => left.sessionId.localeCompare(right.sessionId));
+                        if (sessions.length === 0) {
+                            return { lines: [{ type: 'system', text: 'No JS sessions.' }] };
+                        }
+                        return {
+                            lines: sessions.map((summary) => ({
+                                type: 'output',
+                                text: `${summary.sessionId}${summary.sessionId === activeSessionId ? ' *' : ''} — ` +
+                                    `${summary.title} [${summary.origin}]`,
+                            })),
+                        };
+                    }
+                    case ':attach': {
+                        if (!rest) {
+                            throw new Error('Usage: :attach <session-id>');
+                        }
+                        const attached = getAttachedJsSession(rest);
+                        if (!attached) {
+                            throw new Error(`Unknown attached JS session: ${rest}`);
+                        }
+                        activeSessionId = rest;
+                        activeOrigin = 'attached-runtime';
+                        return {
+                            lines: [{ type: 'system', text: `Attached JS console to runtime session ${rest}` }],
+                            envVars: {
+                                REPL_PROMPT: promptForSession(rest, 'attached-runtime'),
+                            },
+                        };
+                    }
+                    case ':use': {
+                        if (!rest) {
+                            throw new Error('Usage: :use <session-id>');
+                        }
+                        const active = requireSession(rest);
+                        activeSessionId = rest;
+                        activeOrigin = active.origin;
+                        return {
+                            lines: [{ type: 'system', text: `Active JS session: ${rest} [${active.origin}]` }],
+                            envVars: {
+                                REPL_PROMPT: promptForSession(rest, active.origin),
+                            },
+                        };
+                    }
+                    case ':globals': {
+                        const { sessionId, session } = requireSession(rest || undefined);
+                        return {
+                            lines: [
+                                { type: 'system', text: `Globals for ${sessionId}` },
+                                ...session.inspectGlobals().map((name) => ({ type: 'output', text: name })),
+                            ],
+                        };
+                    }
+                    case ':reset': {
+                        const active = requireSession(rest || undefined);
+                        if (active.kind !== 'spawned') {
+                            throw new Error(`Attached JS session ${active.sessionId} cannot be reset`);
+                        }
+                        const { sessionId, session } = active;
+                        await session.reset();
+                        return {
+                            lines: [{ type: 'system', text: `Reset JS session ${sessionId}` }],
+                        };
+                    }
+                    case ':dispose': {
+                        const sessionId = rest || activeSessionId;
+                        if (!sessionId) {
+                            throw new Error('Usage: :dispose <session-id>');
+                        }
+                        if (getAttachedJsSession(sessionId)) {
+                            throw new Error(`Attached JS session ${sessionId} cannot be disposed from JavaScript REPL`);
+                        }
+                        const disposed = broker.disposeSession(sessionId);
+                        if (!disposed) {
+                            throw new Error(`Unknown JS session: ${sessionId}`);
+                        }
+                        if (activeSessionId === sessionId) {
+                            activeSessionId = null;
+                            activeOrigin = null;
+                        }
+                        return {
+                            lines: [{ type: 'system', text: `Disposed JS session ${sessionId}` }],
+                            envVars: {
+                                REPL_PROMPT: promptForSession(null, null),
+                            },
+                        };
+                    }
+                    case ':help': {
+                        const topic = rest || null;
+                        const entries = topic
+                            ? Object.values(COMMAND_HELP).filter((entry) => entry.title === topic)
+                            : Object.values(COMMAND_HELP);
+                        return {
+                            lines: entries.flatMap((entry) => [
+                                { type: 'output', text: `${entry.title} — ${entry.detail}` },
+                                ...(entry.usage ? [{ type: 'system', text: `  ${entry.usage}` }] : []),
+                            ]),
+                        };
+                    }
+                    default:
+                        throw new Error(`Unknown JS REPL command: ${command}`);
+                }
+            }
+            const { session } = requireSession();
+            return {
+                lines: formatEvalLines('eval' in session ? session.eval(trimmed) : session.evaluate(trimmed)),
+            };
+        },
+        getCompletions(input) {
+            const trimmed = input.trimStart();
+            if (trimmed.startsWith(':')) {
+                const token = currentToken(trimmed);
+                if (trimmed.startsWith(':use') ||
+                    trimmed.startsWith(':attach') ||
+                    trimmed.startsWith(':globals')) {
+                    const partial = trimmed.split(/\s+/)[1] ?? '';
+                    return [
+                        ...broker.listSessions().map((summary) => ({ value: summary.sessionId, detail: `${summary.title} [spawned]` })),
+                        ...listAttachedJsSessions().map((entry) => ({
+                            value: entry.summary.sessionId,
+                            detail: `${entry.summary.title} [attached-runtime]`,
+                        })),
+                    ]
+                        .filter((entry) => entry.value.startsWith(partial));
+                }
+                if (trimmed.startsWith(':dispose') || trimmed.startsWith(':reset')) {
+                    const partial = trimmed.split(/\s+/)[1] ?? '';
+                    return broker.listSessions()
+                        .filter((summary) => summary.sessionId.startsWith(partial))
+                        .map((summary) => ({ value: summary.sessionId, detail: summary.title }));
+                }
+                return Object.values(COMMAND_HELP)
+                    .filter((entry) => entry.title.startsWith(token || ':'))
+                    .map((entry) => ({ value: entry.title, detail: entry.detail }));
+            }
+            const token = currentToken(input);
+            let globals = [];
+            if (activeSessionId) {
+                try {
+                    globals = requireSession(activeSessionId).session.inspectGlobals();
+                }
+                catch {
+                    globals = [];
+                }
+            }
+            return [
+                ...JS_KEYWORDS.map((keyword) => ({ value: keyword, detail: 'js keyword' })),
+                ...globals.map((name) => ({ value: name, detail: 'session global' })),
+            ].filter((entry) => entry.value.startsWith(token));
+        },
+        getHelp(topic) {
+            if (!topic) {
+                return Object.values(COMMAND_HELP);
+            }
+            return Object.values(COMMAND_HELP).filter((entry) => entry.title === topic);
+        },
+    };
+}

package/repl/jsSessionBroker.d.ts

@@ -0,0 +1,21 @@
+import { type CreateJsSessionRequest, type JsEvalResult, type JsSessionServiceOptions, type JsSessionSummary } from '../plugin-runtime/jsSessionService';
+export interface SpawnJsSessionRequest extends CreateJsSessionRequest {
+}
+export interface JsSessionHandle {
+    readonly sessionId: string;
+    eval(code: string): JsEvalResult;
+    inspectGlobals(): string[];
+    installPrelude(code: string): void;
+    reset(): Promise<JsSessionSummary>;
+    dispose(): boolean;
+}
+export interface JsSessionBroker {
+    spawnSession(request: SpawnJsSessionRequest): Promise<JsSessionHandle>;
+    getSession(sessionId: string): JsSessionHandle | null;
+    listSessions(): JsSessionSummary[];
+    resetSession(sessionId: string): Promise<JsSessionSummary>;
+    disposeSession(sessionId: string): boolean;
+    clear(): void;
+    subscribe(listener: () => void): () => void;
+}
+export declare function createJsSessionBroker(options?: JsSessionServiceOptions): JsSessionBroker;

package/repl/jsSessionBroker.js

@@ -0,0 +1,75 @@
+import { JsSessionService, } from '../plugin-runtime/jsSessionService';
+export function createJsSessionBroker(options = {}) {
+    const sessionService = new JsSessionService(options);
+    const handles = new Map();
+    const listeners = new Set();
+    function emit() {
+        listeners.forEach((listener) => listener());
+    }
+    function createHandle(sessionId) {
+        return {
+            sessionId,
+            eval(code) {
+                return sessionService.evaluate(sessionId, code);
+            },
+            inspectGlobals() {
+                return sessionService.getGlobalNames(sessionId);
+            },
+            installPrelude(code) {
+                sessionService.installPrelude(sessionId, code);
+            },
+            async reset() {
+                const summary = await sessionService.resetSession(sessionId);
+                emit();
+                return summary;
+            },
+            dispose() {
+                return broker.disposeSession(sessionId);
+            },
+        };
+    }
+    const broker = {
+        async spawnSession(request) {
+            if (handles.has(request.sessionId)) {
+                throw new Error(`JS session already exists: ${request.sessionId}`);
+            }
+            await sessionService.createSession(request);
+            const handle = createHandle(request.sessionId);
+            handles.set(request.sessionId, handle);
+            emit();
+            return handle;
+        },
+        getSession(sessionId) {
+            return handles.get(sessionId) ?? null;
+        },
+        listSessions() {
+            return sessionService.listSessions();
+        },
+        async resetSession(sessionId) {
+            const summary = await sessionService.resetSession(sessionId);
+            emit();
+            return summary;
+        },
+        disposeSession(sessionId) {
+            const disposed = sessionService.disposeSession(sessionId);
+            if (!disposed) {
+                return false;
+            }
+            handles.delete(sessionId);
+            emit();
+            return true;
+        },
+        clear() {
+            sessionService.clear();
+            handles.clear();
+            emit();
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+    };
+    return broker;
+}

package/repl/runtimeBroker.d.ts

@@ -0,0 +1,43 @@
+import type { RuntimeBundleMeta, RuntimeSurfaceId, RuntimeAction, SessionId, StackId } from '../plugin-runtime/contracts';
+import { type QuickJSRuntimeServiceOptions } from '../plugin-runtime/runtimeService';
+import { type RuntimeSessionOwnership } from '../runtime-session-manager/runtimeOwnership';
+export interface SpawnRuntimeSessionRequest {
+    stackId: StackId;
+    sessionId: SessionId;
+    packageIds: string[];
+    bundleCode: string;
+}
+export interface RuntimeSessionSummary {
+    sessionId: SessionId;
+    stackId: StackId;
+    packageIds: string[];
+    surfaces: string[];
+    surfaceTypes?: Record<string, string>;
+    title: string;
+    description?: string;
+    origin: 'spawned' | 'attached';
+    writable: boolean;
+    ownership: RuntimeSessionOwnership;
+}
+export interface RuntimeSessionHandle {
+    readonly sessionId: SessionId;
+    readonly stackId: StackId;
+    readonly origin: 'spawned' | 'attached';
+    readonly writable: boolean;
+    getBundleMeta(): RuntimeBundleMeta;
+    renderSurface(surfaceId: RuntimeSurfaceId, state: unknown): unknown;
+    eventSurface(surfaceId: RuntimeSurfaceId, handler: string, args: unknown, state: unknown): RuntimeAction[];
+    defineSurface(surfaceId: RuntimeSurfaceId, code: string, packId: string): RuntimeBundleMeta;
+    defineSurfaceRender(surfaceId: RuntimeSurfaceId, code: string): RuntimeBundleMeta;
+    defineSurfaceHandler(surfaceId: RuntimeSurfaceId, handler: string, code: string): RuntimeBundleMeta;
+    dispose(): boolean;
+}
+export interface RuntimeBroker {
+    spawnSession(request: SpawnRuntimeSessionRequest): Promise<RuntimeSessionHandle>;
+    getSession(sessionId: SessionId): RuntimeSessionHandle | null;
+    listSessions(): RuntimeSessionSummary[];
+    disposeSession(sessionId: SessionId): boolean;
+    clear(): void;
+    subscribe(listener: () => void): () => void;
+}
+export declare function createRuntimeBroker(options?: QuickJSRuntimeServiceOptions): RuntimeBroker;

package/repl/runtimeBroker.js

@@ -0,0 +1,117 @@
+import { QuickJSRuntimeService } from '../plugin-runtime/runtimeService';
+import { BROKER_OWNED_RUNTIME_SESSION, } from '../runtime-session-manager/runtimeOwnership';
+function toRuntimeSessionSummary(bundle) {
+    return {
+        sessionId: bundle.sessionId,
+        stackId: bundle.stackId,
+        packageIds: [...bundle.packageIds],
+        surfaces: [...bundle.surfaces],
+        surfaceTypes: bundle.surfaceTypes ? { ...bundle.surfaceTypes } : undefined,
+        title: bundle.title,
+        description: bundle.description,
+        origin: 'spawned',
+        writable: true,
+        ownership: BROKER_OWNED_RUNTIME_SESSION,
+    };
+}
+export function createRuntimeBroker(options = {}) {
+    const runtimeService = new QuickJSRuntimeService(options);
+    const handles = new Map();
+    const summaries = new Map();
+    const listeners = new Set();
+    function emit() {
+        listeners.forEach((listener) => listener());
+    }
+    function updateBundle(bundle) {
+        summaries.set(bundle.sessionId, toRuntimeSessionSummary(bundle));
+        emit();
+        return bundle;
+    }
+    function createHandle(bundle) {
+        return {
+            sessionId: bundle.sessionId,
+            stackId: bundle.stackId,
+            origin: 'spawned',
+            writable: true,
+            getBundleMeta() {
+                return {
+                    ...bundle,
+                    packageIds: [...bundle.packageIds],
+                    surfaces: [...bundle.surfaces],
+                    surfaceTypes: bundle.surfaceTypes ? { ...bundle.surfaceTypes } : undefined,
+                };
+            },
+            renderSurface(surfaceId, state) {
+                return runtimeService.renderRuntimeSurface(bundle.sessionId, surfaceId, state);
+            },
+            eventSurface(surfaceId, handler, args, state) {
+                return runtimeService.eventRuntimeSurface(bundle.sessionId, surfaceId, handler, args, state);
+            },
+            defineSurface(surfaceId, code, packId) {
+                bundle = updateBundle(runtimeService.defineRuntimeSurface(bundle.sessionId, surfaceId, code, packId));
+                return bundle;
+            },
+            defineSurfaceRender(surfaceId, code) {
+                bundle = updateBundle(runtimeService.defineRuntimeSurfaceRender(bundle.sessionId, surfaceId, code));
+                return bundle;
+            },
+            defineSurfaceHandler(surfaceId, handler, code) {
+                bundle = updateBundle(runtimeService.defineRuntimeSurfaceHandler(bundle.sessionId, surfaceId, handler, code));
+                return bundle;
+            },
+            dispose() {
+                return broker.disposeSession(bundle.sessionId);
+            },
+        };
+    }
+    const broker = {
+        async spawnSession(request) {
+            if (handles.has(request.sessionId)) {
+                throw new Error(`Runtime session already exists: ${request.sessionId}`);
+            }
+            const bundle = await runtimeService.loadRuntimeBundle(request.stackId, request.sessionId, request.packageIds, request.bundleCode);
+            const handle = createHandle(bundle);
+            handles.set(request.sessionId, handle);
+            updateBundle(bundle);
+            return handle;
+        },
+        getSession(sessionId) {
+            return handles.get(sessionId) ?? null;
+        },
+        listSessions() {
+            return Array.from(summaries.values())
+                .map((summary) => ({
+                ...summary,
+                packageIds: [...summary.packageIds],
+                surfaces: [...summary.surfaces],
+                surfaceTypes: summary.surfaceTypes ? { ...summary.surfaceTypes } : undefined,
+            }))
+                .sort((a, b) => a.sessionId.localeCompare(b.sessionId));
+        },
+        disposeSession(sessionId) {
+            const disposed = runtimeService.disposeSession(sessionId);
+            if (!disposed) {
+                return false;
+            }
+            handles.delete(sessionId);
+            summaries.delete(sessionId);
+            emit();
+            return true;
+        },
+        clear() {
+            for (const sessionId of Array.from(handles.keys())) {
+                runtimeService.disposeSession(sessionId);
+            }
+            handles.clear();
+            summaries.clear();
+            emit();
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+    };
+    return broker;
+}

package/runtime-host/RuntimeSurfaceSessionHost.d.ts

@@ -0,0 +1,8 @@
+import type { RuntimeBundleDefinition } from '@go-go-golems/os-core';
+export interface RuntimeSurfaceSessionHostProps {
+    windowId: string;
+    sessionId: string;
+    bundle: RuntimeBundleDefinition;
+    mode?: 'interactive' | 'preview';
+}
+export declare function RuntimeSurfaceSessionHost({ windowId, sessionId, bundle, mode, }: RuntimeSurfaceSessionHostProps): import("react/jsx-runtime").JSX.Element;