@go-go-golems/os-scripting 0.1.0

package/plugin-runtime/stack-bootstrap.vm.js

@@ -0,0 +1,236 @@
+const __runtimePackageState =
+  globalThis.__runtimePackageState && typeof globalThis.__runtimePackageState === 'object'
+    ? globalThis.__runtimePackageState
+    : {
+        packageIds: [],
+        apis: {},
+      };
+
+globalThis.__runtimePackageState = __runtimePackageState;
+
+let __runtimeBundle = null;
+let __runtimeActions = [];
+
+function isPlainObject(value) {
+  return value && typeof value === 'object' && !Array.isArray(value);
+}
+
+function mergeRuntimeApiValue(existingValue, incomingValue) {
+  if (isPlainObject(existingValue) && isPlainObject(incomingValue)) {
+    const merged = { ...existingValue };
+    for (const [key, value] of Object.entries(incomingValue)) {
+      merged[key] = mergeRuntimeApiValue(merged[key], value);
+    }
+    return merged;
+  }
+
+  return incomingValue;
+}
+
+function registerRuntimePackageApi(packageId, apiExports) {
+  const normalizedPackageId = String(packageId || '').trim();
+  if (!normalizedPackageId) {
+    throw new Error('registerRuntimePackageApi requires a package id');
+  }
+
+  if (!__runtimePackageState.packageIds.includes(normalizedPackageId)) {
+    __runtimePackageState.packageIds.push(normalizedPackageId);
+  }
+
+  if (!isPlainObject(apiExports)) {
+    return;
+  }
+
+  for (const [exportName, exportValue] of Object.entries(apiExports)) {
+    const mergedValue = mergeRuntimeApiValue(__runtimePackageState.apis[exportName], exportValue);
+    __runtimePackageState.apis[exportName] = mergedValue;
+    globalThis[exportName] = mergedValue;
+  }
+}
+
+function collectRuntimePackageApis() {
+  return { ...__runtimePackageState.apis };
+}
+
+function defineRuntimeBundleImpl(factory) {
+  if (typeof factory !== 'function') {
+    throw new Error('defineRuntimeBundle requires a factory function');
+  }
+
+  __runtimeBundle = factory(collectRuntimePackageApis());
+}
+
+function assertStackBundleReady() {
+  if (!__runtimeBundle || typeof __runtimeBundle !== 'object') {
+    throw new Error('Runtime bundle did not register via defineRuntimeBundle');
+  }
+}
+
+function assertSurfacesMap() {
+  assertStackBundleReady();
+  if (!__runtimeBundle.surfaces || typeof __runtimeBundle.surfaces !== 'object') {
+    __runtimeBundle.surfaces = {};
+  }
+  return __runtimeBundle.surfaces;
+}
+
+function normalizeRuntimeSurfacePackId(surfaceId, packId) {
+  const normalizedPackId = typeof packId === 'string' ? packId.trim() : '';
+  if (!normalizedPackId) {
+    throw new Error('Runtime surface packId is required for surface: ' + String(surfaceId));
+  }
+  return normalizedPackId;
+}
+
+function normalizeRuntimeSurfaceDefinition(surfaceId, definitionOrFactory, packId) {
+  const normalizedPackId = normalizeRuntimeSurfacePackId(surfaceId, packId);
+  const definition =
+    typeof definitionOrFactory === 'function'
+      ? definitionOrFactory(collectRuntimePackageApis())
+      : definitionOrFactory;
+
+  if (!definition || typeof definition !== 'object') {
+    throw new Error('Runtime surface definition must be an object for surface: ' + String(surfaceId));
+  }
+
+  if (typeof definition.render !== 'function') {
+    throw new Error('Runtime surface definition render() is required for surface: ' + String(surfaceId));
+  }
+
+  if (definition.handlers !== undefined) {
+    if (!definition.handlers || typeof definition.handlers !== 'object' || Array.isArray(definition.handlers)) {
+      throw new Error('Runtime surface definition handlers must be an object for surface: ' + String(surfaceId));
+    }
+  } else {
+    definition.handlers = {};
+  }
+
+  definition.packId = normalizedPackId;
+  return definition;
+}
+
+function ensureRuntimeSurfaceRecord(surfaceId) {
+  const surfaces = assertSurfacesMap();
+  const key = String(surfaceId);
+  const existing = surfaces[key];
+  if (!existing || typeof existing !== 'object') {
+    surfaces[key] = {
+      handlers: {},
+    };
+  } else if (!existing.handlers || typeof existing.handlers !== 'object') {
+    existing.handlers = {};
+  }
+  return surfaces[key];
+}
+
+function defineRuntimeSurfaceImpl(surfaceId, definitionOrFactory, packId) {
+  const surfaces = assertSurfacesMap();
+  const key = String(surfaceId);
+  surfaces[key] = normalizeRuntimeSurfaceDefinition(key, definitionOrFactory, packId);
+}
+
+function defineRuntimeSurfaceRenderImpl(surfaceId, renderFn) {
+  if (typeof renderFn !== 'function') {
+    throw new Error('defineRuntimeSurfaceRender requires a render function');
+  }
+
+  const surface = ensureRuntimeSurfaceRecord(surfaceId);
+  surface.render = renderFn;
+}
+
+function defineRuntimeSurfaceHandlerImpl(surfaceId, handlerName, handlerFn) {
+  if (typeof handlerFn !== 'function') {
+    throw new Error('defineRuntimeSurfaceHandler requires a handler function');
+  }
+
+  const surface = ensureRuntimeSurfaceRecord(surfaceId);
+  surface.handlers[String(handlerName)] = handlerFn;
+}
+
+globalThis.defineRuntimeBundle = defineRuntimeBundleImpl;
+globalThis.defineRuntimeSurface = defineRuntimeSurfaceImpl;
+globalThis.defineRuntimeSurfaceRender = defineRuntimeSurfaceRenderImpl;
+globalThis.defineRuntimeSurfaceHandler = defineRuntimeSurfaceHandlerImpl;
+globalThis.registerRuntimePackageApi = registerRuntimePackageApi;
+
+globalThis.__runtimeBundleHost = {
+  getMeta() {
+    if (!__runtimeBundle || typeof __runtimeBundle !== 'object') {
+      throw new Error('Runtime bundle did not register via defineRuntimeBundle');
+    }
+
+    if (!__runtimeBundle.surfaces || typeof __runtimeBundle.surfaces !== 'object') {
+      throw new Error('Runtime bundle surfaces must be an object');
+    }
+
+    return {
+      declaredId: typeof __runtimeBundle.id === 'string' ? __runtimeBundle.id : undefined,
+      title: String(__runtimeBundle.title ?? 'Untitled Bundle'),
+      description: typeof __runtimeBundle.description === 'string' ? __runtimeBundle.description : undefined,
+      packageIds: Array.isArray(__runtimeBundle.packageIds)
+        ? __runtimeBundle.packageIds.map((packageId) => String(packageId)).filter((packageId) => packageId.length > 0)
+        : [],
+      initialSessionState: __runtimeBundle.initialSessionState,
+      initialSurfaceState: __runtimeBundle.initialSurfaceState,
+      surfaces: Object.keys(__runtimeBundle.surfaces),
+      surfaceTypes: Object.fromEntries(
+        Object.entries(__runtimeBundle.surfaces).map(([key, surface]) => [
+          key,
+          normalizeRuntimeSurfacePackId(key, surface?.packId),
+        ]),
+      ),
+    };
+  },
+
+  renderRuntimeSurface(surfaceId, state) {
+    const surface = __runtimeBundle?.surfaces?.[surfaceId];
+    if (!surface || typeof surface.render !== 'function') {
+      throw new Error('Runtime surface not found or render() is missing: ' + String(surfaceId));
+    }
+
+    return surface.render({ state });
+  },
+
+  eventRuntimeSurface(surfaceId, handlerName, args, state) {
+    const surface = __runtimeBundle?.surfaces?.[surfaceId];
+    if (!surface) {
+      throw new Error('Runtime surface not found: ' + String(surfaceId));
+    }
+
+    const handler = surface.handlers?.[handlerName];
+    if (typeof handler !== 'function') {
+      throw new Error('Handler not found: ' + String(handlerName));
+    }
+
+    __runtimeActions = [];
+
+    const dispatch = (action) => {
+      __runtimeActions.push(action);
+    };
+
+    handler(
+      {
+        state,
+        dispatch,
+      },
+      args
+    );
+
+    return __runtimeActions.slice();
+  },
+
+  defineRuntimeSurface(surfaceId, definitionOrFactory, packId) {
+    defineRuntimeSurfaceImpl(surfaceId, definitionOrFactory, packId);
+    return this.getMeta();
+  },
+
+  defineRuntimeSurfaceRender(surfaceId, renderFn) {
+    defineRuntimeSurfaceRenderImpl(surfaceId, renderFn);
+    return this.getMeta();
+  },
+
+  defineRuntimeSurfaceHandler(surfaceId, handlerName, handlerFn) {
+    defineRuntimeSurfaceHandlerImpl(surfaceId, handlerName, handlerFn);
+    return this.getMeta();
+  },
+};

package/repl/attachedJsSessionRegistry.d.ts

@@ -0,0 +1,25 @@
+import type { JsEvalResult } from '../plugin-runtime/jsSessionService';
+export interface AttachedJsSessionSummary {
+    sessionId: string;
+    stackId: string;
+    title: string;
+    origin: 'attached-runtime';
+    writable: true;
+}
+export interface AttachedJsSessionHandle {
+    sessionId: string;
+    stackId: string;
+    origin: 'attached-runtime';
+    writable: true;
+    evaluate(code: string): JsEvalResult;
+    inspectGlobals(): string[];
+}
+export interface AttachedJsSessionEntry {
+    handle: AttachedJsSessionHandle;
+    summary: AttachedJsSessionSummary;
+}
+export declare function clearAttachedJsSessions(): void;
+export declare function listAttachedJsSessions(): AttachedJsSessionEntry[];
+export declare function getAttachedJsSession(sessionId: string): AttachedJsSessionEntry | null;
+export declare function subscribeAttachedJsSessions(listener: () => void): () => void;
+export declare function useAttachedJsSessions(): AttachedJsSessionEntry[];

package/repl/attachedJsSessionRegistry.js

@@ -0,0 +1,81 @@
+import { useSyncExternalStore } from 'react';
+import { DEFAULT_RUNTIME_SESSION_MANAGER } from '../runtime-session-manager';
+let snapshot = [];
+const listeners = new Set();
+let unsubscribeManager = null;
+function emit() {
+    listeners.forEach((listener) => listener());
+}
+function rebuildSnapshot() {
+    snapshot = DEFAULT_RUNTIME_SESSION_MANAGER.listSessions()
+        .filter((summary) => summary.status === 'ready' && summary.attachedViewIds.length > 0)
+        .map((summary) => {
+        const handle = DEFAULT_RUNTIME_SESSION_MANAGER.getSession(summary.sessionId);
+        if (!handle) {
+            return null;
+        }
+        return {
+            handle: {
+                sessionId: summary.sessionId,
+                stackId: summary.bundleId,
+                origin: 'attached-runtime',
+                writable: true,
+                evaluate(code) {
+                    return handle.evaluateSessionJs(code);
+                },
+                inspectGlobals() {
+                    return handle.getSessionGlobalNames();
+                },
+            },
+            summary: {
+                sessionId: summary.sessionId,
+                stackId: summary.bundleId,
+                title: summary.title,
+                origin: 'attached-runtime',
+                writable: true,
+            },
+        };
+    })
+        .filter((entry) => entry !== null)
+        .sort((left, right) => left.summary.sessionId.localeCompare(right.summary.sessionId));
+}
+function ensureSubscribed() {
+    if (unsubscribeManager) {
+        return;
+    }
+    rebuildSnapshot();
+    unsubscribeManager = DEFAULT_RUNTIME_SESSION_MANAGER.subscribe(() => {
+        rebuildSnapshot();
+        emit();
+    });
+}
+function releaseSubscriptionIfIdle() {
+    if (listeners.size > 0 || !unsubscribeManager) {
+        return;
+    }
+    unsubscribeManager();
+    unsubscribeManager = null;
+    snapshot = [];
+}
+export function clearAttachedJsSessions() {
+    rebuildSnapshot();
+}
+export function listAttachedJsSessions() {
+    ensureSubscribed();
+    return snapshot;
+}
+export function getAttachedJsSession(sessionId) {
+    ensureSubscribed();
+    return snapshot.find((entry) => entry.summary.sessionId === sessionId) ?? null;
+}
+export function subscribeAttachedJsSessions(listener) {
+    ensureSubscribed();
+    listeners.add(listener);
+    return () => {
+        listeners.delete(listener);
+        releaseSubscriptionIfIdle();
+    };
+}
+export function useAttachedJsSessions() {
+    return useSyncExternalStore(subscribeAttachedJsSessions, listAttachedJsSessions, listAttachedJsSessions);
+}

package/repl/attachedRuntimeSessionRegistry.d.ts

@@ -0,0 +1,11 @@
+import type { SessionId } from '../plugin-runtime/contracts';
+import type { RuntimeSessionHandle, RuntimeSessionSummary } from './runtimeBroker';
+export interface AttachedRuntimeSessionEntry {
+    handle: RuntimeSessionHandle;
+    summary: RuntimeSessionSummary;
+}
+export declare function clearAttachedRuntimeSessions(): void;
+export declare function listAttachedRuntimeSessions(): AttachedRuntimeSessionEntry[];
+export declare function getAttachedRuntimeSession(sessionId: SessionId): AttachedRuntimeSessionEntry | null;
+export declare function subscribeAttachedRuntimeSessions(listener: () => void): () => void;
+export declare function useAttachedRuntimeSessions(): AttachedRuntimeSessionEntry[];

package/repl/attachedRuntimeSessionRegistry.js

@@ -0,0 +1,107 @@
+import { useSyncExternalStore } from 'react';
+import { ATTACHED_READ_ONLY_RUNTIME_SESSION, DEFAULT_RUNTIME_SESSION_MANAGER, } from '../runtime-session-manager';
+let snapshot = [];
+const listeners = new Set();
+let unsubscribeManager = null;
+function emit() {
+    listeners.forEach((listener) => listener());
+}
+function toSummary(summary) {
+    return {
+        sessionId: summary.sessionId,
+        stackId: summary.bundleId,
+        packageIds: [...summary.packageIds],
+        surfaces: [...summary.surfaces],
+        surfaceTypes: summary.surfaceTypes ? { ...summary.surfaceTypes } : undefined,
+        title: summary.title,
+        description: summary.description,
+        origin: 'attached',
+        writable: false,
+        ownership: ATTACHED_READ_ONLY_RUNTIME_SESSION,
+    };
+}
+function toHandle(handle) {
+    return {
+        sessionId: handle.sessionId,
+        stackId: handle.bundleId,
+        origin: 'attached',
+        writable: false,
+        getBundleMeta() {
+            return handle.getBundleMeta();
+        },
+        renderSurface(surfaceId, state) {
+            return handle.renderSurface(surfaceId, state);
+        },
+        eventSurface(surfaceId, handler, args, state) {
+            return handle.eventSurface(surfaceId, handler, args, state);
+        },
+        defineSurface() {
+            throw new Error(`Attached runtime session ${handle.sessionId} is read-only`);
+        },
+        defineSurfaceRender() {
+            throw new Error(`Attached runtime session ${handle.sessionId} is read-only`);
+        },
+        defineSurfaceHandler() {
+            throw new Error(`Attached runtime session ${handle.sessionId} is read-only`);
+        },
+        dispose() {
+            return false;
+        },
+    };
+}
+function rebuildSnapshot() {
+    snapshot = DEFAULT_RUNTIME_SESSION_MANAGER.listSessions()
+        .filter((summary) => summary.status === 'ready' && summary.attachedViewIds.length > 0)
+        .map((summary) => {
+        const handle = DEFAULT_RUNTIME_SESSION_MANAGER.getSession(summary.sessionId);
+        if (!handle) {
+            return null;
+        }
+        return {
+            handle: toHandle(handle),
+            summary: toSummary(summary),
+        };
+    })
+        .filter((entry) => entry !== null)
+        .sort((left, right) => left.summary.sessionId.localeCompare(right.summary.sessionId));
+}
+function ensureSubscribed() {
+    if (unsubscribeManager) {
+        return;
+    }
+    rebuildSnapshot();
+    unsubscribeManager = DEFAULT_RUNTIME_SESSION_MANAGER.subscribe(() => {
+        rebuildSnapshot();
+        emit();
+    });
+}
+function releaseSubscriptionIfIdle() {
+    if (listeners.size > 0 || !unsubscribeManager) {
+        return;
+    }
+    unsubscribeManager();
+    unsubscribeManager = null;
+    snapshot = [];
+}
+export function clearAttachedRuntimeSessions() {
+    rebuildSnapshot();
+}
+export function listAttachedRuntimeSessions() {
+    ensureSubscribed();
+    return snapshot;
+}
+export function getAttachedRuntimeSession(sessionId) {
+    ensureSubscribed();
+    return snapshot.find((entry) => entry.summary.sessionId === sessionId) ?? null;
+}
+export function subscribeAttachedRuntimeSessions(listener) {
+    ensureSubscribed();
+    listeners.add(listener);
+    return () => {
+        listeners.delete(listener);
+        releaseSubscriptionIfIdle();
+    };
+}
+export function useAttachedRuntimeSessions() {
+    return useSyncExternalStore(subscribeAttachedRuntimeSessions, listAttachedRuntimeSessions, listAttachedRuntimeSessions);
+}

package/repl/hypercardReplDriver.d.ts

@@ -0,0 +1,54 @@
+import type { ReplDriver } from '@go-go-golems/os-repl';
+import { type RuntimeBroker } from './runtimeBroker';
+export interface ReplBundleLibraryEntry {
+    key: string;
+    title?: string;
+    stackId: string;
+    packageIds: string[];
+    bundleCode: string;
+    docsMetadata?: RuntimeBundleDocsMetadata;
+}
+export interface HypercardReplDriverOptions {
+    broker?: RuntimeBroker;
+    bundleLibrary?: Record<string, ReplBundleLibraryEntry>;
+}
+interface RuntimePackageDocSymbol {
+    readonly name: string;
+    readonly summary?: string;
+    readonly prose?: string;
+}
+interface RuntimePackageDocFile {
+    readonly package?: {
+        readonly name?: string;
+        readonly title?: string;
+        readonly description?: string;
+        readonly prose?: string;
+    };
+    readonly symbols?: readonly RuntimePackageDocSymbol[];
+}
+interface RuntimePackageDocsMetadata {
+    readonly packId?: string;
+    readonly docs?: {
+        readonly files?: readonly RuntimePackageDocFile[];
+    };
+}
+interface RuntimeBundleDocSymbol {
+    readonly name: string;
+    readonly summary?: string;
+    readonly prose?: string;
+}
+interface RuntimeBundleDocFile {
+    readonly file_path?: string;
+    readonly symbols?: readonly RuntimeBundleDocSymbol[];
+}
+interface RuntimeBundleDocsMetadata {
+    readonly packId?: string;
+    readonly docs?: {
+        readonly files?: readonly RuntimeBundleDocFile[];
+        readonly by_symbol?: Readonly<Record<string, RuntimeBundleDocSymbol>>;
+    };
+}
+export declare function createHypercardReplDriver(options?: HypercardReplDriverOptions): ReplDriver;
+export declare function getRuntimePackageDocsMetadata(packageId: string): RuntimePackageDocsMetadata | null;
+export declare function getHypercardReplDriverState(driver: ReplDriver): Record<string, unknown>;
+export {};