@go-go-golems/os-scripting 0.1.0

package/index.js

@@ -0,0 +1,18 @@
+export * from './app';
+export * from './plugin-runtime';
+export * from './repl/hypercardReplDriver';
+export * from './repl/attachedJsSessionRegistry';
+export * from './repl/attachedRuntimeSessionRegistry';
+export * from './repl/jsReplDriver';
+export * from './repl/jsSessionBroker';
+export * from './repl/runtimeBroker';
+export * from './runtime-session-manager';
+export * from './features/runtimeSessions';
+export * from './hypercard';
+export * from './hypercard/debug/runtimeDebugApp';
+export * from './hypercard/debug/runtimeDebugRegistry';
+export * from './hypercard/task-manager';
+export * from './runtime-packs';
+export * from './runtime-packages';
+export { RuntimeSurfaceSessionHost } from './runtime-host/RuntimeSurfaceSessionHost';
+export { dispatchRuntimeAction } from './runtime-host/pluginIntentRouting';

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@go-go-golems/os-scripting",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "QuickJS runtime, plugin, and REPL-session support for go-go-os.",
+  "keywords": [
+    "quickjs",
+    "runtime",
+    "vm",
+    "scripting",
+    "react",
+    "go-go-os",
+    "go-go-golems"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/go-go-golems/go-go-os-frontend.git",
+    "directory": "packages/os-scripting"
+  },
+  "homepage": "https://github.com/go-go-golems/go-go-os-frontend/tree/main/packages/os-scripting#readme",
+  "bugs": {
+    "url": "https://github.com/go-go-golems/go-go-os-frontend/issues"
+  },
+  "license": "MIT",
+  "author": "Manuel Odendahl",
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "files": [
+    "**/*.js",
+    "**/*.d.ts",
+    "**/*.css",
+    "**/*.vm.js",
+    "**/*.json",
+    "README.md"
+  ],
+  "exports": {
+    ".": "./index.js"
+  },
+  "main": "./index.js",
+  "types": "./index.d.ts",
+  "dependencies": {
+    "@go-go-golems/os-core": "0.1.1",
+    "@go-go-golems/os-chat": "0.1.0",
+    "@go-go-golems/os-repl": "0.1.5",
+    "@codemirror/commands": "^6.10.2",
+    "@codemirror/autocomplete": "^6.18.7",
+    "@codemirror/lang-javascript": "^6.2.4",
+    "@codemirror/language": "^6.12.1",
+    "@codemirror/lint": "^6.8.5",
+    "@codemirror/state": "^6.5.4",
+    "@codemirror/theme-one-dark": "^6.1.3",
+    "@codemirror/view": "^6.39.15",
+    "@jitl/quickjs-singlefile-mjs-release-sync": "^0.31.0",
+    "@jitl/quickjs-ffi-types": "^0.31.0",
+    "@lezer/common": "^1.3.0",
+    "@lezer/highlight": "^1.2.3",
+    "@lezer/javascript": "^1.5.1",
+    "@lezer/lr": "^1.4.2",
+    "quickjs-emscripten": "^0.31.0",
+    "quickjs-emscripten-core": "^0.31.0"
+  },
+  "peerDependencies": {
+    "@reduxjs/toolkit": "^2.0.0",
+    "react": "^18 || ^19",
+    "react-dom": "^18 || ^19",
+    "react-redux": "^9.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/plugin-runtime/contracts.d.ts

@@ -0,0 +1,116 @@
+export type StackId = string;
+export type SessionId = string;
+export type RuntimeSurfaceId = string;
+export interface RuntimeErrorPayload {
+    code: string;
+    message: string;
+    details?: unknown;
+}
+export interface RuntimeAction {
+    type: string;
+    payload?: unknown;
+    meta?: Record<string, unknown>;
+}
+export type RuntimeActionKind = 'draft' | 'filters' | 'domain' | 'system' | 'unknown';
+export declare function getRuntimeActionKind(actionType: string): RuntimeActionKind;
+export declare function getRuntimeActionDomain(actionType: string): string | null;
+export declare function getRuntimeActionOperation(actionType: string): string;
+export interface RuntimeBundleMeta {
+    stackId: StackId;
+    sessionId: SessionId;
+    declaredId?: string;
+    title: string;
+    description?: string;
+    packageIds: string[];
+    initialSessionState?: unknown;
+    initialSurfaceState?: Record<string, unknown>;
+    surfaces: string[];
+    surfaceTypes?: Record<string, string>;
+}
+export interface LoadRuntimeBundleRequest {
+    id: number;
+    type: 'loadRuntimeBundle';
+    stackId: StackId;
+    sessionId: SessionId;
+    code: string;
+}
+export interface RenderRuntimeSurfaceRequest {
+    id: number;
+    type: 'renderRuntimeSurface';
+    sessionId: SessionId;
+    surfaceId: RuntimeSurfaceId;
+    state: unknown;
+}
+export interface EventRuntimeSurfaceRequest {
+    id: number;
+    type: 'eventRuntimeSurface';
+    sessionId: SessionId;
+    surfaceId: RuntimeSurfaceId;
+    handler: string;
+    args?: unknown;
+    state: unknown;
+}
+export interface DefineRuntimeSurfaceRequest {
+    id: number;
+    type: 'defineRuntimeSurface';
+    sessionId: SessionId;
+    surfaceId: RuntimeSurfaceId;
+    code: string;
+    packId: string;
+}
+export interface DefineRuntimeSurfaceRenderRequest {
+    id: number;
+    type: 'defineRuntimeSurfaceRender';
+    sessionId: SessionId;
+    surfaceId: RuntimeSurfaceId;
+    code: string;
+}
+export interface DefineRuntimeSurfaceHandlerRequest {
+    id: number;
+    type: 'defineRuntimeSurfaceHandler';
+    sessionId: SessionId;
+    surfaceId: RuntimeSurfaceId;
+    handler: string;
+    code: string;
+}
+export interface DisposeSessionRequest {
+    id: number;
+    type: 'disposeSession';
+    sessionId: SessionId;
+}
+export interface HealthRequest {
+    id: number;
+    type: 'health';
+}
+export type WorkerRequest = LoadRuntimeBundleRequest | RenderRuntimeSurfaceRequest | EventRuntimeSurfaceRequest | DefineRuntimeSurfaceRequest | DefineRuntimeSurfaceRenderRequest | DefineRuntimeSurfaceHandlerRequest | DisposeSessionRequest | HealthRequest;
+export interface LoadRuntimeBundleResult {
+    bundle: RuntimeBundleMeta;
+}
+export interface RenderRuntimeSurfaceResult {
+    tree: unknown;
+}
+export interface EventRuntimeSurfaceResult {
+    actions: RuntimeAction[];
+}
+export interface DefineRuntimeSurfaceResult {
+    bundle: RuntimeBundleMeta;
+}
+export interface DisposeSessionResult {
+    disposed: boolean;
+}
+export interface HealthResult {
+    ready: true;
+    sessions: string[];
+}
+export type WorkerResult = LoadRuntimeBundleResult | RenderRuntimeSurfaceResult | EventRuntimeSurfaceResult | DefineRuntimeSurfaceResult | DisposeSessionResult | HealthResult;
+export interface WorkerSuccessResponse {
+    id: number;
+    ok: true;
+    result: WorkerResult;
+}
+export interface WorkerErrorResponse {
+    id: number;
+    ok: false;
+    error: RuntimeErrorPayload;
+}
+export type WorkerResponse = WorkerSuccessResponse | WorkerErrorResponse;

package/plugin-runtime/contracts.js

@@ -0,0 +1,32 @@
+const SYSTEM_ACTION_TYPES = new Set(['nav.go', 'nav.back', 'notify.show', 'window.close']);
+export function getRuntimeActionKind(actionType) {
+    if (actionType.startsWith('draft.')) {
+        return 'draft';
+    }
+    if (actionType.startsWith('filters.')) {
+        return 'filters';
+    }
+    if (SYSTEM_ACTION_TYPES.has(actionType)) {
+        return 'system';
+    }
+    const slashIndex = actionType.indexOf('/');
+    if (slashIndex > 0) {
+        return 'domain';
+    }
+    return 'unknown';
+}
+export function getRuntimeActionDomain(actionType) {
+    if (getRuntimeActionKind(actionType) !== 'domain') {
+        return null;
+    }
+    return actionType.split('/', 1)[0] ?? null;
+}
+export function getRuntimeActionOperation(actionType) {
+    if (actionType.startsWith('draft.')) {
+        return actionType.slice('draft.'.length);
+    }
+    if (actionType.startsWith('filters.')) {
+        return actionType.slice('filters.'.length);
+    }
+    return actionType;
+}

package/plugin-runtime/fixtures/column-stack.vm.js

@@ -0,0 +1,19 @@
+defineRuntimeBundle(({ ui }) => {
+  return {
+    id: 'column-demo',
+    title: 'Column Demo',
+    packageIds: ["ui"],
+    surfaces: {
+      main: {
+        packId: 'ui.card.v1',
+        render() {
+          return ui.column([
+            ui.text('top'),
+            ui.text('bottom'),
+          ]);
+        },
+        handlers: {},
+      },
+    },
+  };
+});

package/plugin-runtime/fixtures/dynamic-card.vm.js

@@ -0,0 +1,13 @@
+({ ui }) => ({
+  render({ state }) {
+    return ui.panel([
+      ui.text('Dynamic card: ' + String(state?.draft?.name ?? 'n/a')),
+      ui.button('Back', { onClick: { handler: 'back' } }),
+    ]);
+  },
+  handlers: {
+    back({ dispatch }) {
+      dispatch({ type: 'nav.back' });
+    },
+  },
+})

package/plugin-runtime/fixtures/inventory-stack.vm.js

@@ -0,0 +1,29 @@
+defineRuntimeBundle(({ ui }) => {
+  return {
+    id: 'inventory',
+    title: 'Inventory',
+    packageIds: ["ui"],
+    initialSessionState: { filter: 'all' },
+    initialSurfaceState: { lowStock: { limit: 5 } },
+    surfaces: {
+      lowStock: {
+        packId: 'ui.card.v1',
+        render({ state }) {
+          return ui.panel([
+            ui.text('Filter: ' + String(state?.filters?.filter ?? 'all')),
+            ui.text('Limit: ' + String(state?.draft?.limit ?? 0)),
+            ui.button('Reserve', { onClick: { handler: 'reserve', args: { sku: 'A-1' } } }),
+          ]);
+        },
+        handlers: {
+          reserve({ dispatch }, args) {
+            dispatch({ type: 'draft.set', payload: { path: 'lastSku', value: args?.sku } });
+            dispatch({ type: 'filters.set', payload: { path: 'filter', value: 'low-stock' } });
+            dispatch({ type: 'inventory/reserve-item', payload: { sku: args?.sku } });
+            dispatch({ type: 'notify.show', payload: { level: 'info', message: 'reserved' } });
+          },
+        },
+      },
+    },
+  };
+});

package/plugin-runtime/fixtures/kanban-card.vm.js

@@ -0,0 +1,55 @@
+({ widgets }) => ({
+  render({ state }) {
+    const board = state?.app_kanban ?? {};
+
+    return widgets.kanban.page(
+      widgets.kanban.taxonomy({
+        issueTypes: Array.isArray(board.taxonomy?.issueTypes) ? board.taxonomy.issueTypes : [{ id: 'feature', label: 'Feature', icon: '✨' }],
+        priorities: Array.isArray(board.taxonomy?.priorities) ? board.taxonomy.priorities : [{ id: 'high', label: 'High', icon: '▲' }],
+        labels: Array.isArray(board.taxonomy?.labels) ? board.taxonomy.labels : [{ id: 'frontend', label: 'Frontend', icon: '🖼️' }],
+      }),
+      widgets.kanban.header({
+        title: 'Sprint Board',
+        subtitle: 'Fixture board',
+        searchQuery: typeof board.searchQuery === 'string' ? board.searchQuery : '',
+      }),
+      widgets.kanban.highlights({
+        items: [
+          {
+            id: 'total',
+            label: 'Total',
+            value: Array.isArray(board.tasks) ? board.tasks.length : 0,
+            tone: 'accent',
+          },
+        ],
+      }),
+      widgets.kanban.filters({
+        filterType: board.filterType ?? null,
+        filterPriority: board.filterPriority ?? null,
+      }),
+      widgets.kanban.board({
+        columns: Array.isArray(board.columns) ? board.columns : [],
+        tasks: Array.isArray(board.tasks) ? board.tasks : [],
+        editingTask: board.editingTask ?? null,
+        collapsedCols:
+          board.collapsedCols && typeof board.collapsedCols === 'object' && !Array.isArray(board.collapsedCols)
+            ? board.collapsedCols
+            : {},
+        onMoveTask: { handler: 'moveTask' },
+      }),
+      widgets.kanban.status({
+        metrics: [
+          { label: 'total', value: Array.isArray(board.tasks) ? board.tasks.length : 0 },
+        ],
+      }),
+    );
+  },
+  handlers: {
+    moveTask({ dispatch }, args) {
+      dispatch({
+        type: 'kanban/move-task',
+        payload: args,
+      });
+    },
+  },
+})

package/plugin-runtime/fixtures/loop-stack.vm.js

@@ -0,0 +1,16 @@
+defineRuntimeBundle(({ ui }) => {
+  return {
+    id: 'loop',
+    title: 'Loop',
+    packageIds: ["ui"],
+    surfaces: {
+      loop: {
+        packId: 'ui.card.v1',
+        render() {
+          while (true) {}
+        },
+        handlers: {},
+      },
+    },
+  };
+});

package/plugin-runtime/fixtures/patched-low-stock-handler.vm.js

@@ -0,0 +1,3 @@
+({ dispatch }) => {
+  dispatch({ type: 'notify.show', payload: { level: 'info', message: 'patched-handler' } });
+}

package/plugin-runtime/fixtures/patched-low-stock-render.vm.js

@@ -0,0 +1,5 @@
+({ state }) =>
+  ui.panel([
+    ui.text('Patched limit: ' + String(state?.draft?.limit ?? 0)),
+    ui.button('Reserve', { onClick: { handler: 'reserve', args: { sku: 'A-1' } } }),
+  ])

package/plugin-runtime/index.d.ts

@@ -0,0 +1,6 @@
+export * from './contracts';
+export * from './intentSchema';
+export * from './jsSessionService';
+export * from './quickJsSessionCore';
+export * from './runtimeSurfaceRegistry';
+export * from './runtimeService';

package/plugin-runtime/index.js

@@ -0,0 +1,6 @@
+export * from './contracts';
+export * from './intentSchema';
+export * from './jsSessionService';
+export * from './quickJsSessionCore';
+export * from './runtimeSurfaceRegistry';
+export * from './runtimeService';

package/plugin-runtime/intentSchema.d.ts

@@ -0,0 +1,3 @@
+import type { RuntimeAction } from './contracts';
+export declare function validateRuntimeAction(value: unknown): RuntimeAction;
+export declare function validateRuntimeActions(value: unknown): RuntimeAction[];

package/plugin-runtime/intentSchema.js

@@ -0,0 +1,25 @@
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+export function validateRuntimeAction(value) {
+    if (!isRecord(value)) {
+        throw new Error('Runtime action must be an object');
+    }
+    if (typeof value.type !== 'string' || value.type.length === 0) {
+        throw new Error('Runtime action type must be a non-empty string');
+    }
+    if (value.meta !== undefined && !isRecord(value.meta)) {
+        throw new Error('Runtime action meta must be an object when provided');
+    }
+    return {
+        type: value.type,
+        payload: value.payload,
+        meta: value.meta,
+    };
+}
+export function validateRuntimeActions(value) {
+    if (!Array.isArray(value)) {
+        throw new Error('Runtime actions result must be an array');
+    }
+    return value.map((action) => validateRuntimeAction(action));
+}

package/plugin-runtime/jsEvalSupport.d.ts

@@ -0,0 +1,6 @@
+import { type QuickJsSessionVm } from './quickJsSessionCore';
+import type { JsEvalResult } from './jsSessionService';
+export declare function installJsEvalBridge(vm: QuickJsSessionVm, filename: string, timeoutMs: number): void;
+export declare function consumeJsEvalLogs(vm: QuickJsSessionVm, filename: string, timeoutMs: number): string[];
+export declare function evaluateQuickJsSessionJs(vm: QuickJsSessionVm, code: string, filename: string, evalTimeoutMs: number, inspectTimeoutMs: number): JsEvalResult;
+export declare function getQuickJsSessionGlobalNames(vm: QuickJsSessionVm, filename: string, timeoutMs: number): string[];

package/plugin-runtime/jsEvalSupport.js

@@ -0,0 +1,93 @@
+import { evalQuickJsCodeOrThrow, evalQuickJsToNative, } from './quickJsSessionCore';
+const JS_EVAL_BRIDGE_BOOTSTRAP_SOURCE = `
+  if (!globalThis.__jsEvalHost) {
+    globalThis.__jsEvalHost = {
+      logs: [],
+      pushLog(text) {
+        this.logs.push(String(text));
+      },
+      consumeLogs() {
+        const copy = this.logs.slice();
+        this.logs.length = 0;
+        return copy;
+      }
+    };
+
+    const __existingConsole = globalThis.console && typeof globalThis.console === 'object'
+      ? globalThis.console
+      : {};
+    const __baseLog = typeof __existingConsole.log === 'function'
+      ? __existingConsole.log.bind(__existingConsole)
+      : null;
+
+    globalThis.console = {
+      ...__existingConsole,
+      log(...args) {
+        globalThis.__jsEvalHost.pushLog(args.map((arg) => String(arg)).join(' '));
+        if (__baseLog) {
+          return __baseLog(...args);
+        }
+      }
+    };
+  }
+`;
+function valueTypeOf(value) {
+    if (value === null) {
+        return 'null';
+    }
+    if (Array.isArray(value)) {
+        return 'array';
+    }
+    return typeof value;
+}
+function asError(error) {
+    if (error instanceof Error) {
+        const [name, ...rest] = error.message.split(':');
+        if (rest.length > 0 && name.trim().length > 0) {
+            return {
+                name: name.trim(),
+                message: rest.join(':').trim(),
+            };
+        }
+        return {
+            name: 'Error',
+            message: error.message,
+        };
+    }
+    return {
+        name: 'Error',
+        message: String(error),
+    };
+}
+export function installJsEvalBridge(vm, filename, timeoutMs) {
+    evalQuickJsCodeOrThrow(vm, JS_EVAL_BRIDGE_BOOTSTRAP_SOURCE, filename, timeoutMs);
+}
+export function consumeJsEvalLogs(vm, filename, timeoutMs) {
+    try {
+        return evalQuickJsToNative(vm, 'globalThis.__jsEvalHost.consumeLogs()', filename, timeoutMs);
+    }
+    catch {
+        return [];
+    }
+}
+export function evaluateQuickJsSessionJs(vm, code, filename, evalTimeoutMs, inspectTimeoutMs) {
+    try {
+        const value = evalQuickJsToNative(vm, code, filename, evalTimeoutMs);
+        return {
+            value,
+            valueType: valueTypeOf(value),
+            logs: consumeJsEvalLogs(vm, `${filename}.consume-logs.js`, inspectTimeoutMs),
+        };
+    }
+    catch (error) {
+        return {
+            value: undefined,
+            valueType: 'error',
+            logs: consumeJsEvalLogs(vm, `${filename}.consume-logs.js`, inspectTimeoutMs),
+            error: asError(error),
+        };
+    }
+}
+export function getQuickJsSessionGlobalNames(vm, filename, timeoutMs) {
+    return evalQuickJsToNative(vm, 'Object.getOwnPropertyNames(globalThis).sort()', filename, timeoutMs);
+}

package/plugin-runtime/jsSessionService.d.ts

@@ -0,0 +1,55 @@
+export interface JsSessionServiceOptions {
+    memoryLimitBytes?: number;
+    stackLimitBytes?: number;
+    loadTimeoutMs?: number;
+    evalTimeoutMs?: number;
+    inspectTimeoutMs?: number;
+}
+export interface CreateJsSessionRequest {
+    sessionId: string;
+    title?: string;
+    scopeId?: string;
+    preludeCode?: string;
+    bootstrapSources?: Array<{
+        code: string;
+        filename: string;
+    }>;
+}
+export interface JsSessionSummary {
+    sessionId: string;
+    title: string;
+    createdAt: string;
+    globalNames: string[];
+}
+export interface JsEvalError {
+    name: string;
+    message: string;
+}
+export interface JsEvalResult {
+    value: unknown;
+    valueType: string;
+    logs: string[];
+    error?: JsEvalError;
+}
+export declare class JsSessionService {
+    private readonly options;
+    private readonly sessions;
+    constructor(options?: JsSessionServiceOptions);
+    private getRecordOrThrow;
+    private createRecord;
+    createSession(request: CreateJsSessionRequest): Promise<JsSessionSummary>;
+    getSummary(sessionId: string): JsSessionSummary;
+    listSessions(): JsSessionSummary[];
+    evaluate(sessionId: string, code: string): JsEvalResult;
+    evaluateToNative<T>(sessionId: string, code: string, filename: string, timeoutMs: number): T;
+    runCode(sessionId: string, code: string, filename: string, timeoutMs: number): void;
+    getGlobalNames(sessionId: string): string[];
+    resetSession(sessionId: string): Promise<JsSessionSummary>;
+    disposeSession(sessionId: string): boolean;
+    clear(): void;
+    health(): {
+        ready: true;
+        sessions: string[];
+    };
+    installPrelude(sessionId: string, code: string): void;
+}