arcane-os 0.54.1 → 0.56.0

package/src/core/runtime.mjs

@@ -0,0 +1,345 @@
+import Is from 'strong-type';
+import {createArcaneEventSource} from '../event-manager.mjs';
+import {CORE_PROTOCOL, CoreError, serializeCoreError} from '../../browser-runtime/core/contracts.mjs';
+
+const is = new Is(false);
+const STATE_EVENT = 'core.runtime.state';
+const FRAME_EVENT = 'core.runtime.frame';
+
+function failure(code, message) {
+    return new CoreError({code, message});
+}
+
+function requireFunction(value, name) {
+    if (!is.function(value)) throw new TypeError(`${name} must be a function.`);
+}
+
+function aborted(controller) {
+    if (controller.signal.aborted) throw controller.signal.reason;
+}
+
+/** App-neutral dispatch. Hosts own services, privileges and process lifetime. */
+class CoreRuntime {
+    #application;
+    #version;
+    #events;
+    #state = 'created';
+    #services = new Map();
+    #methods = new Map();
+    #requests = new Map();
+    #responses = new Set();
+    #publications = [];
+    #publishing = false;
+    #closing = null;
+
+    constructor({application, version, services = []} = {}) {
+        this.#application = application;
+        this.#version = version;
+        this.#events = createArcaneEventSource(
+            this,
+            {source: 'core-runtime', eventTypes: [STATE_EVENT, FRAME_EVENT]}
+        );
+        for (const service of services) this.registerService(service);
+    }
+
+    current() {
+        return {
+            state: this.#state,
+            application: this.#application,
+            version: this.#version,
+            services: [...this.#services.values()].map(
+                function serviceState(service) {
+                    return {name: service.name, state: service.state, error: service.error};
+                }
+            ),
+            activeRequests: [...this.#requests.values()].map(
+                function requestState(request) {
+                    return {id: request.id, method: request.method, lifetime: request.lifetime};
+                }
+            )
+        };
+    }
+
+    subscribe(listener, {emitCurrent = true, signal} = {}) {
+        requireFunction(listener, 'listener');
+        function deliverState(occurrence) {
+            listener(occurrence.detail);
+        }
+        const unsubscribe = this.#events.on(STATE_EVENT, deliverState, {signal});
+        try {
+            if (emitCurrent && !signal?.aborted) listener(this.current());
+        } catch (error) {
+            unsubscribe();
+            throw error;
+        }
+        return unsubscribe;
+    }
+
+    onFrame(listener, {signal} = {}) {
+        requireFunction(listener, 'listener');
+        function deliverFrame(occurrence) {
+            listener(occurrence.detail);
+        }
+        return this.#events.on(FRAME_EVENT, deliverFrame, {signal});
+    }
+
+    #publish(replay = false) {
+        this.#publications.push({state: this.current(), replay});
+        if (this.#publishing) return;
+        this.#publishing = true;
+        try {
+            // A synchronous subscriber can change the lifecycle. Finish each
+            // state publication before delivering its reentrant successor.
+            while (this.#publications.length) {
+                const {state, replay: replaying} = this.#publications.shift();
+                // Finish one replay snapshot before publishing lifecycle changes
+                // triggered reentrantly by its listeners.
+                if (replaying && state.state === 'ready') {
+                    this.emit('core.ready', {version: state.version, app: state.application});
+                }
+                this.#events.dispatch(STATE_EVENT, state);
+                this.emit('core.state', state);
+                if (replaying) {
+                    for (const service of state.services) this.emit('core.service.state', service);
+                }
+            }
+        } finally {
+            this.#publishing = false;
+        }
+    }
+
+    emit(event, data) {
+        const frame = {protocol: CORE_PROTOCOL, type: 'event', event, data, time: new Date().toISOString()};
+        this.#events.dispatch(FRAME_EVENT, frame);
+        return frame;
+    }
+
+    registerService(definition) {
+        if (this.#closing) throw failure('CORE_CLOSING', 'Core is closing.');
+        const {name, methods = {}, start, drain, dispose} = definition;
+        if (!is.string(name) || !name) throw new TypeError('Service name must be a nonempty string.');
+        if (this.#services.has(name)) throw failure('CORE_SERVICE_EXISTS', `Service ${name} is already registered.`);
+        for (const [hook, value] of Object.entries({start, drain, dispose})) {
+            if (value !== undefined) requireFunction(value, `Service ${hook}`);
+        }
+        const registrations = [];
+        for (const [method, value] of Object.entries(methods)) {
+            if (this.#methods.has(method) || ['system.ping', 'app.current', 'version.current'].includes(method)) {
+                throw failure('CORE_METHOD_EXISTS', `Method ${method} is already registered.`);
+            }
+            const handle = is.function(value) ? value : value.handle;
+            const lifetime = is.function(value) ? 'request' : value.lifetime ?? 'request';
+            requireFunction(handle, `Method ${method}`);
+            if (lifetime !== 'request' && lifetime !== 'service') {
+                throw new TypeError('Method lifetime must be request or service.');
+            }
+            registrations.push({method, handle, lifetime});
+        }
+        const service = {name, definition, state: 'registered', error: null, task: null};
+        this.#services.set(name, service);
+        for (const registration of registrations) this.#methods.set(registration.method, {...registration, service});
+        if (this.#state === 'ready') this.#startService(service);
+        const runtime = this;
+        return {
+            get ready() {
+                return runtime.#startService(service);
+            },
+            current() {
+                return {name: service.name, state: service.state, error: service.error};
+            }
+        };
+    }
+
+    #serviceContext(service) {
+        const runtime = this;
+        return {
+            application: this.#application,
+            service: service.name,
+            emit(event, data) {
+                return runtime.emit(event, data);
+            }
+        };
+    }
+
+    #serviceState(service, state, error) {
+        service.state = state;
+        service.error = state === 'failed' || (error !== undefined && error !== null)
+            ? serializeCoreError(error)
+            : null;
+        this.emit('core.service.state', {name: service.name, state, error: service.error});
+        this.#publish();
+    }
+
+    #startService(service) {
+        if (service.task) return service.task;
+        if (this.#closing) return Promise.reject(failure('CORE_CLOSING', 'Core is closing.'));
+        const runtime = this;
+        // Publish after task assignment so a synchronous state subscriber cannot
+        // start the same service twice.
+        service.task = Promise.resolve().then(
+            async function initializeService() {
+                runtime.#serviceState(service, 'starting');
+                try {
+                    await service.definition.start?.(runtime.#serviceContext(service));
+                    runtime.#serviceState(service, 'ready');
+                } catch (error) {
+                    runtime.#serviceState(service, 'failed', error);
+                    throw error;
+                }
+            }
+        );
+        service.task.catch(function observeServiceStartupFailure() {});
+        return service.task;
+    }
+
+    start() {
+        if (this.#closing) throw failure('CORE_CLOSING', 'Core is closing.');
+        if (this.#state === 'ready') return this.current();
+        this.#state = 'ready';
+        for (const service of this.#services.values()) this.#startService(service);
+        this.emit('core.ready', {version: this.#version, app: this.#application});
+        this.#publish();
+        return this.current();
+    }
+
+    async handle(frame) {
+        if (frame?.protocol !== CORE_PROTOCOL) throw failure('INVALID_RPC_REQUEST', 'Unknown Core protocol.');
+        if (frame.type === 'control') {
+            if (frame.control === 'runtime.replay') {
+                this.#publish(true);
+                return;
+            }
+            if (frame.control === 'request.cancel') return this.#cancel(frame.requestId);
+            if (frame.control === 'requests.cancelAll') {
+                for (const request of this.#requests.values()) this.#cancel(request.id);
+                return;
+            }
+            throw failure('INVALID_RPC_CONTROL', 'Unknown Core control.');
+        }
+        if (frame.type !== 'request' || !is.string(frame.id) || !frame.id || !is.string(frame.method)) {
+            throw failure('INVALID_RPC_REQUEST', 'A Core request requires an id and method.');
+        }
+        const task = this.#answer(frame);
+        this.#responses.add(task);
+        try {
+            return await task;
+        } finally {
+            this.#responses.delete(task);
+        }
+    }
+
+    async #answer(frame) {
+        let result;
+        let error;
+        let ok = true;
+        try {
+            if (this.#state !== 'ready') throw failure('CORE_NOT_READY', 'Core is not accepting requests.');
+            if (this.#requests.has(frame.id)) throw failure('RPC_REQUEST_ID_ACTIVE', 'The request id is already active.');
+            if (frame.method === 'system.ping') result = {ok: true};
+            else if (frame.method === 'version.current') result = this.#version;
+            else if (frame.method === 'app.current') result = this.#application;
+            else result = await this.#request(frame);
+        } catch (caught) {
+            ok = false;
+            error = caught;
+        }
+        const response = {
+            protocol: CORE_PROTOCOL,
+            type: 'response',
+            id: frame.id,
+            ...(ok ? {ok: true, result} : {ok: false, error: serializeCoreError(error)}),
+            time: new Date().toISOString()
+        };
+        this.#events.dispatch(FRAME_EVENT, response);
+        return response;
+    }
+
+    #request(frame) {
+        const registration = this.#methods.get(frame.method);
+        if (!registration) throw failure('METHOD_NOT_ALLOWED', `Core does not expose ${frame.method}.`);
+        const {service, handle, lifetime} = registration;
+        const controller = new AbortController();
+        const request = {id: frame.id, method: frame.method, lifetime, controller, task: null};
+        const runtime = this;
+        this.#requests.set(frame.id, request);
+        request.task = Promise.resolve().then(
+            async function executeCoreRequest() {
+                try {
+                    await runtime.#startService(service);
+                    aborted(controller);
+                    const result = await handle.call(
+                        service.definition,
+                        frame.parameters,
+                        {...runtime.#serviceContext(service), requestId: frame.id, signal: controller.signal}
+                    );
+                    aborted(controller);
+                    return result;
+                } finally {
+                    if (runtime.#requests.get(frame.id) === request) runtime.#requests.delete(frame.id);
+                    runtime.#publish();
+                }
+            }
+        );
+        this.#publish();
+        return request.task;
+    }
+
+    #cancel(id) {
+        const request = this.#requests.get(id);
+        if (!request || request.lifetime === 'service' || request.controller.signal.aborted) return false;
+        const error = failure('REQUEST_ABORTED', 'The Core request was cancelled.');
+        error.name = 'AbortError';
+        request.controller.abort(error);
+        return true;
+    }
+
+    close() {
+        if (this.#closing) return this.#closing;
+        this.#state = 'draining';
+        const runtime = this;
+        // A synchronous state listener may call close again. Retain the owner
+        // before announcing draining, and never let a renderer cancel saves.
+        this.#closing = Promise.resolve().then(
+            async function drainCoreRuntime() {
+                const failures = [];
+                for (const request of runtime.#requests.values()) runtime.#cancel(request.id);
+                await Promise.allSettled([...runtime.#responses]);
+                await Promise.all(
+                    [...runtime.#services.values()].map(
+                        async function closeCoreService(service) {
+                            const serviceFailures = [];
+                            if (service.task) {
+                                try { await service.task; } catch (error) { serviceFailures.push(error); }
+                            }
+                            runtime.#serviceState(service, 'draining');
+                            for (const hook of ['drain', 'dispose']) {
+                                try {
+                                    await service.definition[hook]?.(runtime.#serviceContext(service));
+                                } catch (error) {
+                                    serviceFailures.push(error);
+                                    runtime.emit('core.error', serializeCoreError(error));
+                                }
+                            }
+                            const error = serviceFailures.length
+                                ? new AggregateError(serviceFailures, `Service ${service.name} shutdown failed.`)
+                                : null;
+                            failures.push(...serviceFailures);
+                            runtime.#serviceState(service, 'closed', error);
+                        }
+                    )
+                );
+                runtime.#state = 'closed';
+                runtime.#publish();
+                runtime.#events.dispose();
+                if (failures.length) throw new AggregateError(failures, 'Core service shutdown failed.');
+                return runtime.current();
+            }
+        );
+        this.#publish();
+        return this.#closing;
+    }
+}
+
+export function createCoreRuntime(options) {
+    return new CoreRuntime(options);
+}

package/src/core/stdio.mjs

@@ -0,0 +1,209 @@
+import {finished} from 'node:stream';
+import Is from 'strong-type';
+import {CoreError, serializeCoreError} from '../../browser-runtime/core/contracts.mjs';
+
+const is = new Is(false);
+
+/** Content-Length is used only for the existing native transport framing. */
+export function encodeCoreFrame(frame) {
+    const body = Buffer.from(JSON.stringify(frame), 'utf8');
+    return Buffer.concat([Buffer.from(`Content-Length: ${body.length}\r\n\r\n`, 'ascii'), body]);
+}
+
+export function createCoreFrameDecoder(onFrame) {
+    let header = Buffer.alloc(0);
+    let remaining = null;
+    let parts = [];
+    const utf8 = new TextDecoder('utf-8', {fatal: true});
+
+    function push(chunk) {
+        let input = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        while (input.length || remaining === 0) {
+            if (remaining === null) {
+                header = Buffer.concat([header, input]);
+                const marker = header.indexOf('\r\n\r\n');
+                if (marker < 0) return;
+                const match = header.subarray(0, marker).toString('ascii').match(
+                    /(?:^|\r\n)Content-Length:\s*(\d+)(?:\r\n|$)/i
+                );
+                if (!match) throw new CoreError({code: 'IPC_LENGTH_MISSING', message: 'IPC content length is missing.'});
+                remaining = Number(match[1]);
+                if (!is.safeInteger(remaining) || remaining < 0) {
+                    throw new CoreError({code: 'IPC_LENGTH_INVALID', message: 'IPC content length is invalid.'});
+                }
+                input = header.subarray(marker + 4);
+                header = Buffer.alloc(0);
+            }
+            const consumed = Math.min(remaining, input.length);
+            if (consumed) parts.push(input.subarray(0, consumed));
+            input = input.subarray(consumed);
+            remaining -= consumed;
+            if (remaining > 0) return;
+            const body = Buffer.concat(parts);
+            parts = [];
+            remaining = null;
+            onFrame(JSON.parse(utf8.decode(body)));
+        }
+    }
+
+    function finish() {
+        if (header.length || remaining !== null) {
+            throw new CoreError({code: 'IPC_FRAME_INCOMPLETE', message: 'IPC ended during a frame.'});
+        }
+    }
+
+    return {push, finish};
+}
+
+function reportStdioError(error) {
+    console.error('Arcane Core transport failed:', error);
+}
+
+/** Attach an existing runtime; EOF drains accepted service work, never exits. */
+export function startCoreStdio({runtime, input = process.stdin, output = process.stdout, onError = reportStdioError}) {
+    let closing = null;
+    let writes = Promise.resolve();
+    let outputFailed = false;
+    let inputCompleted = false;
+    let resolveInputCompletion;
+    const inputCompletion = new Promise(function observeInputCompletion(resolve) {
+        resolveInputCompletion = resolve;
+    });
+    const pending = new Set();
+    const failures = [];
+    let resolveClosed;
+    let rejectClosed;
+    const closed = new Promise(
+        function createClosedPromise(resolve, reject) {
+            resolveClosed = resolve;
+            rejectClosed = reject;
+        }
+    );
+    // Every background error is reported to onError and retained by closed.
+    closed.catch(function observeReportedTransportFailure() {});
+
+    function report(error) {
+        if (failures.includes(error)) return;
+        failures.push(error);
+        try { onError(error); } catch (reportError) { failures.push(reportError); }
+    }
+
+    function failOutput(error) {
+        outputFailed = true;
+        report(error);
+        close();
+    }
+
+    function queueFrame(frame) {
+        if (outputFailed) return;
+        let encoded;
+        try { encoded = encodeCoreFrame(frame); } catch (error) { failOutput(error); return; }
+        writes = writes.then(
+            function writeNextFrame() {
+                if (outputFailed) return;
+                return new Promise(
+                    function writeFrame(resolve, reject) {
+                        output.write(
+                            encoded,
+                            function frameWritten(error) {
+                                if (error) reject(error);
+                                else resolve();
+                            }
+                        );
+                    }
+                );
+            }
+        ).catch(failOutput);
+    }
+
+    const unsubscribe = runtime.onFrame(queueFrame);
+
+    function receiveFrame(frame) {
+        const task = runtime.handle(frame);
+        pending.add(task);
+        task.then(
+            function requestSettled() {
+                pending.delete(task);
+            },
+            function requestFailed(error) {
+                pending.delete(task);
+                report(error);
+                try { runtime.emit('core.error', serializeCoreError(error)); } catch (eventError) { report(eventError); }
+            }
+        );
+    }
+
+    const decoder = createCoreFrameDecoder(receiveFrame);
+
+    function receiveInput(chunk) {
+        try { decoder.push(chunk); } catch (error) { report(error); close(); }
+    }
+
+    function inputEnded() {
+        try { decoder.finish(); } catch (error) { report(error); }
+        close();
+    }
+
+    function inputFailed(error) {
+        report(error);
+        close();
+    }
+
+    function detachInput() {
+        input.off('data', receiveInput);
+        input.off('end', inputEnded);
+        input.off('close', inputEnded);
+        input.pause();
+    }
+
+    async function releaseTransportListeners() {
+        unsubscribe();
+        output.off('error', failOutput);
+        // destroy(error) marks a stream destroyed before its scheduled error
+        // and close events. The native completion owner observes their delivery;
+        // stream flags alone do not establish that pending errors were observed.
+        if (input.destroyed && !inputCompleted) await inputCompletion;
+        cleanupInputCompletion();
+        input.off('error', inputFailed);
+    }
+
+    function close() {
+        if (closing) return closed;
+        detachInput();
+        closing = Promise.resolve().then(
+            async function drainTransport() {
+                try { await runtime.close(); } catch (error) { report(error); }
+                await Promise.allSettled([...pending]);
+                await writes;
+                await releaseTransportListeners();
+                if (failures.length) rejectClosed(new AggregateError(failures, 'Core transport closed with errors.'));
+                else resolveClosed(runtime.current());
+            }
+        );
+        closing.catch(
+            async function shutdownFailed(error) {
+                report(error);
+                await releaseTransportListeners();
+                rejectClosed(new AggregateError(failures, 'Core transport shutdown failed.'));
+            }
+        );
+        return closed;
+    }
+
+    const cleanupInputCompletion = finished(input, {readable: true, writable: false}, function inputLifecycleComplete() {
+        inputCompleted = true;
+        resolveInputCompletion();
+    });
+    input.on('data', receiveInput);
+    input.on('end', inputEnded);
+    input.on('close', inputEnded);
+    input.on('error', inputFailed);
+    output.on('error', failOutput);
+    try { runtime.start(); } catch (error) { report(error); close(); }
+    if (!closing) {
+        if (input.errored) report(input.errored);
+        if (input.readableEnded || input.destroyed) inputEnded();
+        else input.resume();
+    }
+    return {runtime, closed, close};
+}

package/src/core-classic-source.mjs

@@ -0,0 +1,43 @@
+import {readFile} from 'node:fs/promises';
+
+/**
+ * Generate the native host's classic script from the canonical ESM client.
+ * The two owned modules have declaration exports and two explicit imports;
+ * this projection is deliberately not a general JavaScript bundler.
+ */
+export async function createCoreClassicSource({eventOwnerModuleURL,replayRuntimeState=false}={}){
+    if(typeof eventOwnerModuleURL!=='string'||!eventOwnerModuleURL){
+        throw new TypeError('The classic Core client needs the served SDK event-manager module URL.');
+    }
+    const [contracts,client]=await Promise.all([
+        readFile(new URL('../browser-runtime/core/contracts.mjs',import.meta.url),'utf8'),
+        readFile(new URL('../browser-runtime/core/client.mjs',import.meta.url),'utf8')
+    ]);
+    const declarations=contracts.replace(/^export (?=(?:const|class|function) )/gmu,'');
+    const implementation=client
+        .replace("import {arcaneEvents} from '../event-manager.mjs';",'')
+        .replace("import {CORE_PROTOCOL,CORE_READY_EVENTS,CoreError,serializeCoreError} from './contracts.mjs';",'')
+        .replace(/^export (?=function )/gmu,'');
+    return `(function installArcaneCoreClassic(global){
+    'use strict';
+    const arcaneEvents=global.arcaneEvents??null;
+${declarations}
+${implementation}
+    if(global[CORE_CLIENT_KEY])return;
+    function loadSharedEventOwner(){
+        return import(${JSON.stringify(eventOwnerModuleURL)}).then(function sharedEventOwner(namespace){return namespace.arcaneEvents;});
+    }
+    // Document-created native injection precedes the page's managed import map.
+    // Only the module import waits for parsing; facade/RPC setup below is immediate.
+    const eventOwnerReady=arcaneEvents?Promise.resolve(arcaneEvents)
+        :global.document?.readyState==='loading'
+            ?new Promise(function afterImportMap(resolve,reject){
+                global.document.addEventListener('DOMContentLoaded',function connectSharedEvents(){
+                    loadSharedEventOwner().then(resolve,reject);
+                },{once:true});
+            })
+            :loadSharedEventOwner();
+    installCoreClient(global,{eventOwner:arcaneEvents,eventOwnerReady,replayRuntimeState:${replayRuntimeState===true}});
+})(globalThis);
+`;
+}

package/src/import-map.mjs

@@ -42,6 +42,8 @@ const STATIC_RUNTIME_PACKAGE_IMPORTS=new Map([
 const SDK_BROWSER_SELF_IMPORTS=new Map([
     ['arcane-os/event-manager',SDK_BROWSER_ENTRY],
     ['arcane-os/websocket-client','sdk/websocket-client.mjs'],
+    ['arcane-os/core/client','sdk/core/client.mjs'],
+    ['arcane-os/core/contracts','sdk/core/contracts.mjs'],
     ['arcane-os/logging','sdk/logging.mjs'],
     ['arcane-os/browser-device','sdk/browser-device.mjs'],
     ['arcane-os/pwa','sdk/pwa.mjs'],
@@ -2087,6 +2089,66 @@ function scanHtmlStructure(html){
     return {scripts,links,bases,metas,elements,styles,headClose,bodyClose};
 }
 
+/** Remove generated PWA references from a selected output document without changing authored content. */
+export function removePwaEntryReferences(html, {documentUrl, manifestUrl} = {}) {
+    if (!is.string(html)) throw new TypeError('PWA entry HTML must be a string.');
+    const structure = scanHtmlStructure(html);
+    const manifest = new URL(manifestUrl, documentUrl);
+    const base = structure.bases.find(
+        function baseWithHref(element) {
+            return parseTagAttributes(element.open).has('href');
+        }
+    );
+    const baseHref = base ? structuralAttribute(parseTagAttributes(base.open), 'href', 'base') : null;
+    const resourceBase = baseHref ? new URL(baseHref, documentUrl) : documentUrl;
+    const edits = [];
+    for (const link of structure.links) {
+        const attributes = parseTagAttributes(link.open);
+        const href = htmlAttributeView(attributes.get('href') ?? '');
+        const rel = htmlAttributeView(attributes.get('rel') ?? '');
+        if (!href?.decoded || !rel) continue;
+        let target;
+        try {
+            target = new URL(href.decoded, resourceBase);
+        } catch (error) {
+            // An unrelated non-URL reference stays under its authored owner.
+            continue;
+        }
+        if (target.origin !== manifest.origin || target.pathname !== manifest.pathname) continue;
+        const tokens = [...rel.decoded.matchAll(/[^\t\n\f\r ]+/gu)];
+        const manifestTokens = tokens.filter(
+            function manifestRelationship(token) {
+                return asciiLower(token[0]) === 'manifest';
+            }
+        );
+        if (manifestTokens.length === 0) continue;
+        if (manifestTokens.length === tokens.length) {
+            edits.push(
+                {start: link.start, end: link.end, value: ''}
+            );
+            continue;
+        }
+        const position = attributes.positions.get('rel');
+        for (const token of manifestTokens) {
+            edits.push(
+                {
+                    start: link.start + position.start + rel.positions[token.index],
+                    end: link.start + position.start + rel.positions[token.index + token[0].length],
+                    value: ''
+                }
+            );
+        }
+    }
+    for (const script of structure.scripts) {
+        if (parseTagAttributes(script.open).has('data-arcane-pwa')) {
+            edits.push(
+                {start: script.start, end: script.end, value: ''}
+            );
+        }
+    }
+    return applyReferenceEdits(html, edits);
+}
+
 /** Update only active PWA entry references; registration never orders application startup. */
 export function applyPwaEntryReferences(html,{manifestUrl,bootstrapUrl}={}){
     if(!is.string(html))throw new TypeError('PWA entry HTML must be a string.');