arcane-os 0.1.0-dev.5

package/src/event-queue.mjs

@@ -0,0 +1,138 @@
+import {AsyncLocalStorage} from 'node:async_hooks';
+import {arcaneEvents} from './event-manager.mjs';
+
+const deliveryStorage=new AsyncLocalStorage();
+
+function deliveryOccurrence(event){
+    const active=deliveryStorage.getStore();
+    if(active&&!active.closed&&Object.is(active.event,event)){
+        return active;
+    }
+    return {
+        event,
+        managers:new Set(),
+        pending:0,
+        closed:false
+    };
+}
+
+function mirror(manager,event,eventMetadata,occurrence){
+    if(!manager||!event||typeof event!=='object'||occurrence.managers.has(manager)){
+        return;
+    }
+    occurrence.managers.add(manager);
+    try{
+        const result=manager.forward(event,eventMetadata);
+        if(result&&typeof result.then==='function'){
+            void Promise.resolve(result).catch(()=>{});
+        }
+    }catch{
+        // Central instrumentation is observational. Its subscribers must not
+        // replace the queue callback's backpressure or failure semantics.
+    }
+}
+
+function callbackError(value){
+    if(value instanceof Error){
+        return value;
+    }
+    return new Error(`The event callback failed: ${String(value)}`,{cause:value});
+}
+
+export function createEventQueue(onEvent,{
+    onFailure,
+    eventManager=arcaneEvents,
+    eventMetadata={source:'sdk',category:'operation'}
+}={}){
+    const callback=typeof onEvent==='function'?onEvent:null;
+    const manager=eventManager===null?null:eventManager;
+    if(manager&&typeof manager.forward!=='function'){
+        throw new TypeError('The central event manager must provide forward(event, metadata).');
+    }
+    let firstError=null;
+    let tail=Promise.resolve();
+    const pendingKeys=new Set();
+    let resolveFailure;
+    const failure=new Promise(resolve=>{
+        resolveFailure=resolve;
+    });
+
+    const capture=error=>{
+        if(firstError){
+            return;
+        }
+        firstError=callbackError(error);
+        resolveFailure(firstError);
+        try{
+            const result=onFailure?.(firstError);
+            if(result&&typeof result.then==='function'){
+                void Promise.resolve(result).catch(()=>{});
+            }
+        }catch{
+            // The callback failure remains authoritative. Failure cleanup must
+            // never create a second unhandled error.
+        }
+    };
+
+    const enqueue=(event,{coalesce}={})=>{
+        if((!callback&&!manager)||firstError){
+            return tail;
+        }
+        if(coalesce&&pendingKeys.has(coalesce)){
+            return tail;
+        }
+        if(coalesce){
+            pendingKeys.add(coalesce);
+        }
+        const occurrence=deliveryOccurrence(event);
+        occurrence.pending+=1;
+        const task=tail.then(()=>deliveryStorage.run(occurrence,async()=>{
+            if(firstError){
+                return;
+            }
+            const current=Object.freeze(event);
+            mirror(manager,current,eventMetadata,occurrence);
+            try{
+                await callback?.(current);
+            }catch(error){
+                capture(error);
+            }
+        }));
+        tail=task.finally(()=>{
+            occurrence.pending-=1;
+            if(occurrence.pending===0){
+                occurrence.closed=true;
+            }
+            if(coalesce){
+                pendingKeys.delete(coalesce);
+            }
+        }).catch(capture);
+        return tail;
+    };
+
+    const send=async event=>{
+        await enqueue(event);
+        if(firstError){
+            throw firstError;
+        }
+    };
+
+    const drain=async()=>{
+        let observed;
+        do{
+            observed=tail;
+            await observed;
+        }while(observed!==tail);
+        if(firstError){
+            throw firstError;
+        }
+    };
+
+    return Object.freeze({
+        drain,
+        enqueue,
+        failure,
+        send,
+        get error(){return firstError;}
+    });
+}

package/src/events.mjs

@@ -0,0 +1,219 @@
+import {randomUUID} from 'node:crypto';
+import {CLI_EVENT_PROTOCOL,OUTPUT_MODES} from './constants.mjs';
+import {ArcaneError,ERROR_CODES,errorRecord} from './errors.mjs';
+
+function write(stream,value){
+    stream.write(`${value}\n`);
+}
+
+function jsonSafe(value,seen=new WeakSet()){
+    if(value===undefined||value===null||typeof value==='string'
+        ||typeof value==='number'||typeof value==='boolean'){
+        return value;
+    }
+
+    if(typeof value==='bigint'){
+        return value.toString();
+    }
+
+    if(typeof value==='function'||typeof value==='symbol'){
+        return undefined;
+    }
+
+    if(value instanceof Error){
+        return errorRecord(value);
+    }
+
+    if(Array.isArray(value)){
+        if(seen.has(value)){
+            return undefined;
+        }
+
+        seen.add(value);
+        const result=value.map(item=>jsonSafe(item,seen)).filter(item=>item!==undefined);
+        seen.delete(value);
+        return result;
+    }
+
+    if(typeof value==='object'){
+        if(seen.has(value)){
+            return undefined;
+        }
+
+        seen.add(value);
+        const result={};
+        for(const [key,item] of Object.entries(value)){
+            const safe=jsonSafe(item,seen);
+            if(safe!==undefined){
+                result[key]=safe;
+            }
+        }
+        seen.delete(value);
+        return result;
+    }
+
+    return String(value);
+}
+
+function humanEvent(event){
+    const label=event.message||event.type;
+    return `[${event.sequence}] ${label}`;
+}
+
+export function createReporter({
+    command,
+    output='human',
+    stdout=process.stdout,
+    stderr=process.stderr,
+    operationId=randomUUID(),
+    clock=()=>new Date()
+}={}){
+    if(!OUTPUT_MODES.includes(output)){
+        throw new ArcaneError(
+            ERROR_CODES.usage,
+            `Unsupported output mode: ${String(output)}. Expected human, json, or ndjson.`
+        );
+    }
+
+    let sequence=0;
+    let accepted=false;
+    let terminal=false;
+
+    function event(type,{message,data,status}={}){
+        return {
+            protocol:CLI_EVENT_PROTOCOL,
+            operationId,
+            sequence:++sequence,
+            timestamp:clock().toISOString(),
+            command,
+            type,
+            ...(status?{status}:{}),
+            ...(message?{message}:{}),
+            ...(data===undefined?{}:{data:jsonSafe(data)})
+        };
+    }
+
+    function streamEvent(current){
+        if(output==='ndjson'){
+            write(stdout,JSON.stringify(current));
+        }else if(output==='json'){
+            write(stderr,JSON.stringify(current));
+        }else{
+            write(stderr,humanEvent(current));
+        }
+        return current;
+    }
+
+    function accept(data){
+        if(accepted){
+            return null;
+        }
+        accepted=true;
+        return streamEvent(event('operation.accepted',{
+            status:'accepted',
+            message:`Accepted ${command}.`,
+            data
+        }));
+    }
+
+    function emit(type,data,message){
+        if(!accepted){
+            throw new ArcaneError(
+                ERROR_CODES.operationFailed,
+                'The operation must be accepted before work events are emitted.'
+            );
+        }
+        if(terminal){
+            return null;
+        }
+        return streamEvent(event(type,{message,data,status:'running'}));
+    }
+
+    function complete(result){
+        if(terminal){
+            return null;
+        }
+        terminal=true;
+        const current=event('operation.completed',{
+            status:'completed',
+            message:`Completed ${command}.`,
+            data:{result}
+        });
+
+        if(output==='ndjson'){
+            write(stdout,JSON.stringify(current));
+        }else if(output==='json'){
+            write(stdout,JSON.stringify({
+                protocol:CLI_EVENT_PROTOCOL,
+                ok:true,
+                operationId,
+                command,
+                result:jsonSafe(result)
+            }));
+        }else{
+            if(result!==undefined){
+                if(typeof result==='string'){
+                    write(stdout,result);
+                }else{
+                    write(stdout,JSON.stringify(jsonSafe(result),null,2));
+                }
+            }
+            write(stderr,humanEvent(current));
+        }
+        return current;
+    }
+
+    function reject(error){
+        if(terminal){
+            return null;
+        }
+        terminal=true;
+        const normalized=errorRecord(error);
+        const current=event(
+            normalized.code===ERROR_CODES.cancelled?'operation.cancelled':'operation.failed',
+            {
+                status:normalized.code===ERROR_CODES.cancelled?'cancelled':'failed',
+                message:normalized.message,
+                data:{error:normalized}
+            }
+        );
+
+        if(output==='ndjson'){
+            write(stdout,JSON.stringify(current));
+        }else if(output==='json'){
+            write(stdout,JSON.stringify({
+                protocol:CLI_EVENT_PROTOCOL,
+                ok:false,
+                operationId,
+                command,
+                error:normalized
+            }));
+        }else{
+            write(stderr,`${normalized.code}: ${normalized.message}`);
+        }
+        return current;
+    }
+
+    function forward(value,data){
+        if(typeof value==='string'){
+            return emit(value,data);
+        }
+        if(value&&typeof value==='object'){
+            const {type='operation.progress',message,...rest}=value;
+            return emit(type,rest.data??rest,message);
+        }
+        return emit('operation.progress',data);
+    }
+
+    return {
+        operationId,
+        output,
+        accept,
+        emit,
+        forward,
+        complete,
+        reject,
+        get accepted(){return accepted;},
+        get terminal(){return terminal;}
+    };
+}

package/src/index.mjs

@@ -0,0 +1,177 @@
+export {
+    ARCANE_MACHINE_BUNDLE_VERSION,
+    ARCANE_PROTOCOL,
+    ARCANE_UPSTREAM_COMMIT,
+    ARCANE_UPSTREAM_REPOSITORY,
+    CLI_EVENT_PROTOCOL,
+    CLI_NAME,
+    OUTPUT_MODES,
+    RUNTIME_ROOT,
+    SDK_NAME,
+    SDK_ROOT,
+    SDK_VERSION,
+    TARGET_ADAPTER_PROTOCOL,
+    TARGET_IDS
+} from './constants.mjs';
+
+export {
+    ArcaneError,
+    ERROR_CODES,
+    errorRecord,
+    fail,
+    normalizeError,
+    throwIfAborted
+} from './errors.mjs';
+
+export {createReporter} from './events.mjs';
+export {
+    SDK_UPDATE_REGISTRY,
+    SDK_UPDATE_TIMEOUT_MS,
+    checkForSdkUpdate,
+    compareSdkVersions,
+    updateTagForVersion,
+    validateUpdateRegistry
+} from './update-check.mjs';
+export {
+    ARCANE_EVENT_STACK_PROTOCOL,
+    arcaneEvents,
+    createDOMInstrumentation,
+    createEventManager,
+    DEFAULT_DOM_EVENT_TYPES,
+    describeDOMTarget,
+    DOM_INTERACTION_EVENT,
+    DOM_MUTATION_EVENT,
+    DOM_OBSERVATION_STARTED_EVENT,
+    DOM_OBSERVATION_STOPPED_EVENT,
+    domSelector,
+    EventManager,
+    parseEventStack,
+    PLAYBACK_CANCELLED_EVENT,
+    PLAYBACK_COMPLETED_EVENT,
+    PLAYBACK_FAILED_EVENT,
+    PLAYBACK_RECORD_EVENT,
+    PLAYBACK_STARTED_EVENT,
+    TIME_TRAVEL_OVERFLOW_EVENT,
+    TIME_TRAVEL_SEEK_EVENT
+} from './event-manager.mjs';
+export {runProcess} from './process.mjs';
+export {
+    DEFAULT_TEST_TIMEOUT_MS,
+    registeredTestCount,
+    runRegisteredTests,
+    test
+} from './testing.mjs';
+export {runDoctor,assessArcaneOllama} from './doctor.mjs';
+export {
+    ARCANE_NATIVE_PROVIDER_PATHS,
+    ARCANE_PORTABLE_PROVIDER_PATH,
+    loadArcaneNativeProvider,
+    loadArcanePortableProvider
+} from './native-provider-loader.mjs';
+export {
+    ARCANE_INTEGRATED_PROVIDER_RELATIVE_PATH,
+    INTEGRATED_TOOLCHAIN_PROTOCOL,
+    loadArcaneIntegratedProvider
+} from './integrated-provider-loader.mjs';
+export {
+    repositoryPull,
+    repositoryPush,
+    repositoryStatus,
+    runRepositoryAction
+} from './repository.mjs';
+export {
+    buildTarget,
+    createNativeTargetAdapter,
+    getTargetAdapter,
+    listTargets,
+    runTarget,
+    verifyTarget
+} from './targets/index.mjs';
+export {
+    assertIntegratedNativeToolchain,
+    assertIntegratedPortableToolchain,
+    assertNativeApplicationToolchainCompatibility,
+    assertPortableToolchainCompatibility,
+    buildApplication,
+    bundleApplication,
+    checkApplication,
+    checkSdkUpdate,
+    createApplication,
+    createToolchain,
+    describeTargets,
+    developApplication,
+    doctorApplication,
+    doctorNativeTarget,
+    executeOperation,
+    initializeApplication,
+    packageApplication,
+    planApplication,
+    prepareNativeTarget,
+    resolveNativeBuildOutputRoot,
+    resolvePortableBuildOutputRoot,
+    repositoryApplication,
+    runApplication,
+    testApplication,
+    verifyApplication,
+    verifyBundleApplication,
+    verifyNativeArtifact
+} from './toolchain.mjs';
+export {createWorkspace,initWorkspace} from './scaffold.mjs';
+export {
+    authenticateRuntimeReceipt,
+    getSdkRoot,
+    loadRuntimeRelease,
+    readVerifiedRuntimeFile,
+    verifyRuntime
+} from './runtime.mjs';
+export {
+    discoverApps,
+    inspectWorkspaceProfile,
+    resolveWorkspace,
+    selectApp,
+    validateWorkspace
+} from './workspace.mjs';
+export {startDevServer} from './dev-server.mjs';
+export {
+    NATIVE_BUILD_PLAN_PROTOCOL,
+    NATIVE_BUILDER_PROTOCOL,
+    assertNativeToolchainCompatibility,
+    authenticateNativeBuildPlan,
+    createNativeBuildPlan,
+    executeNativeBuildPlan,
+    validateNativeBuilder
+} from './native-plan.mjs';
+export {
+    APP_DESCRIPTOR_NAME,
+    APP_DESCRIPTOR_SCHEMA_VERSION,
+    appDescriptorSha256,
+    loadAppDescriptor,
+    projectNativeDescriptor,
+    projectPackageManifest,
+    validateAppDescriptor
+} from './app-descriptor.mjs';
+export {
+    authenticateAppReleaseAuthority,
+    authenticateAppReleaseReceipt,
+    authenticateSharedPayloadSnapshot,
+    discoverApps as discoverPackagerApps,
+    inspectApp,
+    packageApp,
+    prepareSharedPayloadSnapshot,
+    readVerifiedAppReleaseFile,
+    verifyApp
+} from './packager/core.mjs';
+export {
+    APP_BUNDLE_DESCRIPTOR_NAME,
+    APP_BUNDLE_EXTENSION,
+    APP_BUNDLE_FORMAT,
+    APP_BUNDLE_KIND,
+    APP_BUNDLE_LIMITS,
+    APP_BUNDLE_MANIFEST_NAME,
+    APP_BUNDLE_RELEASE_PATH,
+    APP_BUNDLE_SCHEMA_VERSION,
+    createAppReleaseBundle,
+    createCanonicalUstarHeader,
+    validateAppBundlePath,
+    verifyAppReleaseBundle
+} from './release-bundle.mjs';