arcane-os 0.56.0 → 0.58.0

package/src/process.mjs

@@ -45,10 +45,30 @@ async function emitLines(events,type,text){
     }
 }
 
-function deliverChunk(stream,events,type,text){
+function outputSelected(option,stream){
+    return is.boolean(option)?option:option?.[stream]??true;
+}
+
+function outputEncodingSelected(option,stream){
+    const selected=option!==null&&is.object(option)?option[stream]:option;
+    const encoding=selected===undefined?'utf8':selected;
+    if(encoding!=='utf8'&&encoding!==null){
+        throw new TypeError(`The ${stream} outputEncoding must be 'utf8' or null.`);
+    }
+    return encoding;
+}
+
+function deliverChunk(stream,events,type,chunk,{onOutput,emitOutput,onFailure}){
     stream.pause();
-    return emitLines(events,type,text).catch(()=>{
-        // The queue owns and propagates the first callback failure.
+    return (async function deliverOutput(){
+        try{
+            if(onOutput)await onOutput({stream:type==='process.stdout'?'stdout':'stderr',chunk});
+        }catch(error){
+            onFailure(error);
+        }
+        if(emitOutput)await emitLines(events,type,chunk);
+    })().catch(()=>{
+        // The event queue separately owns and propagates observer failures.
     }).finally(()=>{
         if(!stream.destroyed){
             stream.resume();
@@ -121,15 +141,40 @@ export async function runProcess(command,args=[],{
     env,
     signal,
     onEvent,
+    onOutput,
+    captureOutput=true,
+    emitOutputEvents=true,
+    outputEncoding='utf8',
     heartbeatMs=5000,
     terminationGraceMs=DEFAULT_TERMINATION_GRACE_MS,
     allowNonzero=false,
-    input
+    input,
+    cancellationMode='terminate-tree'
 }={}){
     throwIfAborted(signal);
+    if(onOutput!==undefined&&!is.function(onOutput)){
+        throw new TypeError('onOutput must be a function.');
+    }
+    const outputEncodings={
+        stdout:outputEncodingSelected(outputEncoding,'stdout'),
+        stderr:outputEncodingSelected(outputEncoding,'stderr')
+    };
+    for(const stream of ['stdout','stderr']){
+        if(outputEncodings[stream]===null&&(!onOutput
+            ||outputSelected(captureOutput,stream)!==false
+            ||outputSelected(emitOutputEvents,stream)!==false)){
+            throw new TypeError(`Raw ${stream} requires onOutput, captureOutput:false and emitOutputEvents:false for that stream.`);
+        }
+    }
+    if(!onOutput&&(!outputSelected(captureOutput,'stdout')||!outputSelected(captureOutput,'stderr'))){
+        throw new TypeError('Uncaptured process output requires an onOutput consumer.');
+    }
     if(!is.array(args)||args.some(argument=>!is.string(argument))){
         throw new ArcaneError(ERROR_CODES.usage,'Process arguments must be a fixed array of strings.');
     }
+    if(cancellationMode!=='terminate-tree'&&cancellationMode!=='close-input'){
+        throw new ArcaneError(ERROR_CODES.usage,'Unknown process cancellation mode.');
+    }
     if(!is.integer(terminationGraceMs)||terminationGraceMs<100||terminationGraceMs>30_000){
         throw new ArcaneError(
             ERROR_CODES.usage,
@@ -151,20 +196,39 @@ export async function runProcess(command,args=[],{
     throwIfAborted(signal);
 
     return new Promise((resolve,reject)=>{
-        let stdout='';
-        let stderr='';
+        let stdout=outputEncodings.stdout!==null&&outputSelected(captureOutput,'stdout')?'':null;
+        let stderr=outputEncodings.stderr!==null&&outputSelected(captureOutput,'stderr')?'':null;
+        let childClosed=false;
+        let closedResult=null;
         let settlementStarted=false;
         let cancellationRequested=false;
         let cancellationError=null;
         let terminationRequested=false;
         let escalation=null;
         let spawnError=null;
+        let inputError=null;
+        let inputIterator=null;
+        let inputPump=null;
+        let inputReturn=null;
+        let inputDone=false;
+        const outputErrors=[];
         let child;
         let heartbeat=null;
         const deliveries=new Set();
 
         const ownDelivery=(stream,type,chunk)=>{
-            const delivery=deliverChunk(stream,events,type,chunk);
+            const name=type==='process.stdout'?'stdout':'stderr';
+            const delivery=deliverChunk(stream,events,type,chunk,{
+                onOutput,
+                emitOutput:outputEncodings[name]!==null&&outputSelected(emitOutputEvents,name),
+                onFailure:function outputFailed(error){
+                    // Preserve complete failed callback input even when the
+                    // caller elected not to retain successful protocol output.
+                    outputErrors.push(new ArcaneError(ERROR_CODES.operationFailed,
+                        `The ${name} output callback failed.`,{cause:error,details:{stream:name,chunk}}));
+                    stopTree();
+                }
+            });
             deliveries.add(delivery);
             void delivery.then(()=>deliveries.delete(delivery));
         };
@@ -175,6 +239,26 @@ export async function runProcess(command,args=[],{
             }
         };
 
+        function stopInput(){
+            if(inputIterator&&!inputDone&&!inputReturn){
+                inputReturn=Promise.resolve().then(async function returnInput(){
+                    await inputIterator.return?.();
+                }).catch(function inputReturnFailed(error){
+                    inputError=inputError&&inputError!==error
+                        ?new AggregateError([inputError,error],'Process input and its cleanup failed.'):error;
+                });
+            }
+            child?.stdin.end();
+        }
+
+        async function drainInput(){
+            stopInput();
+            // AsyncIterable producers own cancellation of an outstanding next().
+            // Their return() must cooperate so owned cleanup can really finish.
+            await inputPump;
+            await inputReturn;
+        }
+
         const finish=(callback,value)=>{
             if(settlementStarted){
                 return;
@@ -184,9 +268,38 @@ export async function runProcess(command,args=[],{
             clearTimeout(escalation);
             signal?.removeEventListener('abort',abort);
             void (async()=>{
+                await drainInput();
+                let callbackFailure=null;
                 try{
                     await events.drain();
-                }catch(callbackFailure){
+                }catch(error){
+                    callbackFailure=error;
+                }
+                if((cancellationMode==='close-input'&&closedResult)||inputIterator||onOutput){
+                    const failures=[...new Set([
+                        callback===reject?value:null,
+                        callbackFailure,inputError,cancellationError,spawnError,...outputErrors
+                    ].filter(error=>error!==null))];
+                    if(failures.length>0){
+                        const primary=failures[0];
+                        // Owned cancellation/exit errors already carry this exact
+                        // result. Other errors retain their identity and cause in
+                        // the complete failure record instead of being rewritten.
+                        if(failures.length===1&&primary?.details===closedResult){
+                            reject(primary);
+                            return;
+                        }
+                        const failure=new ArcaneError(
+                            primary?.code??ERROR_CODES.operationFailed,
+                            primary?.message??`Could not complete ${command}.`,
+                            {cause:primary,details:closedResult,exitCode:primary?.exitCode}
+                        );
+                        failure.errors=failures;
+                        reject(failure);
+                        return;
+                    }
+                }
+                if(callbackFailure){
                     reject(callbackFailure);
                     return;
                 }
@@ -195,10 +308,16 @@ export async function runProcess(command,args=[],{
         };
 
         const stopTree=()=>{
-            if(terminationRequested||settlementStarted){
+            if(terminationRequested||settlementStarted||childClosed){
                 return;
             }
             terminationRequested=true;
+            stopInput();
+            if(cancellationMode==='close-input'){
+                // The selected host owns shutdown after EOF. Keep observing its
+                // complete output and exit; accepted durable work may outlive UI.
+                return;
+            }
             terminateProcessTree(child);
             escalation=setTimeout(()=>{
                 if(childIsRunning(child)){
@@ -214,7 +333,7 @@ export async function runProcess(command,args=[],{
         };
 
         const abort=()=>{
-            if(cancellationRequested||settlementStarted){
+            if(cancellationRequested||settlementStarted||childClosed){
                 return;
             }
             cancellationRequested=true;
@@ -225,7 +344,9 @@ export async function runProcess(command,args=[],{
             );
             void events.enqueue({
                 type:'process.cancellation.requested',
-                message:`Stopping ${command} and its child processes.`,
+                message:cancellationMode==='close-input'
+                    ?`Closing ${command} input and waiting for its owned shutdown.`
+                    :`Stopping ${command} and its child processes.`,
                 data:{command,pid:child?.pid??null}
             });
             stopTree();
@@ -263,16 +384,16 @@ export async function runProcess(command,args=[],{
             return;
         }
 
-        // Each readable retains split UTF-8 sequences and flushes at EOF.
-        // Capture and events consume the same decoded text.
-        child.stdout.setEncoding('utf8');
-        child.stderr.setEncoding('utf8');
+        // Text streams retain split UTF-8 sequences and flush at EOF. Explicit
+        // raw streams bypass decoding and deliver native Buffers only to onOutput.
+        if(outputEncodings.stdout!==null)child.stdout.setEncoding(outputEncodings.stdout);
+        if(outputEncodings.stderr!==null)child.stderr.setEncoding(outputEncodings.stderr);
         child.stdout.on('data',chunk=>{
-            stdout=appendOutput(stdout,chunk);
+            if(stdout!==null)stdout=appendOutput(stdout,chunk);
             ownDelivery(child.stdout,'process.stdout',chunk);
         });
         child.stderr.on('data',chunk=>{
-            stderr=appendOutput(stderr,chunk);
+            if(stderr!==null)stderr=appendOutput(stderr,chunk);
             ownDelivery(child.stderr,'process.stderr',chunk);
         });
         child.on('error',error=>{
@@ -286,8 +407,13 @@ export async function runProcess(command,args=[],{
             }
         });
         child.on('close',(code,terminationSignal)=>{
+            // The child lifetime has ended even while its output/event callbacks
+            // are still draining. A later abort cannot cancel that completed work.
+            childClosed=true;
+            signal?.removeEventListener('abort',abort);
             clearInterval(heartbeat);
             void (async()=>{
+                await drainInput();
                 await drainDeliveries();
                 if(settlementStarted)return;
                 const result={
@@ -299,10 +425,11 @@ export async function runProcess(command,args=[],{
                     stdout,
                     stderr
                 };
+                closedResult=result;
                 if(terminationRequested){
                     // The direct child has exited. Make one final tree-wide attempt so
                     // a descendant that ignored the graceful request cannot outlive it.
-                    terminateProcessTree(child,{force:true});
+                    if(cancellationMode!=='close-input')terminateProcessTree(child,{force:true});
                     if(cancellationRequested){
                         await events.enqueue({
                             type:'process.cancelled',
@@ -310,7 +437,8 @@ export async function runProcess(command,args=[],{
                             data:{command,code:result.code,signal:terminationSignal}
                         });
                     }
-                    finish(reject,events.error??cancellationError??new ArcaneError(
+                    if(cancellationError)cancellationError.details=result;
+                    finish(reject,events.error??inputError??outputErrors[0]??cancellationError??new ArcaneError(
                         ERROR_CODES.operationFailed,
                         `Stopped ${command} after its event callback failed.`
                     ));
@@ -324,6 +452,16 @@ export async function runProcess(command,args=[],{
                     ));
                     return;
                 }
+                if(inputError){
+                    finish(reject,new ArcaneError(ERROR_CODES.operationFailed,
+                        `Could not write ${command} input: ${inputError.message}`,
+                        {cause:inputError,details:result}));
+                    return;
+                }
+                if(outputErrors.length){
+                    finish(reject,outputErrors[0]);
+                    return;
+                }
                 await events.enqueue({
                     type:'process.completed',
                     message:`${command} exited with code ${String(result.code)}.`,
@@ -346,7 +484,33 @@ export async function runProcess(command,args=[],{
             abort();
         }
 
-        if(input!==undefined){
+        if(input&&is.function(input[Symbol.asyncIterator])){
+            child.stdin.on('error',error=>{inputError=error;stopTree();});
+            inputPump=(async function pumpInput(){
+                try{
+                    inputIterator=input[Symbol.asyncIterator]();
+                    while(!terminationRequested&&!childClosed){
+                        const next=await inputIterator.next();
+                        if(next.done){inputDone=true;break;}
+                        if(terminationRequested||childClosed)break;
+                        await new Promise(function writeChunk(resolve,reject){
+                            child.stdin.write(next.value,function written(error){
+                                if(error)reject(error);
+                                else resolve();
+                            });
+                        });
+                    }
+                    child.stdin.end();
+                }catch(error){
+                    inputError=inputError&&inputError!==error
+                        ?new AggregateError([inputError,error],'Process input failed.'):error;
+                    stopTree();
+                }
+            })();
+        }else if(cancellationMode==='close-input'){
+            child.stdin.on('error',error=>{inputError=error;stopTree();});
+            if(input!==undefined&&!terminationRequested)child.stdin.write(input);
+        }else if(input!==undefined){
             child.stdin.end(input);
         }else{
             child.stdin.end();

package/src/scaffold.mjs

@@ -44,7 +44,7 @@ function validateInputs(appId,displayName){
 }
 
 function validateScaffoldTarget(target){
-    const targets=['browser','portable','windows-x64','linux-x64','linux-arm64','android-arm64'];
+    const targets=['browser','portable','windows-x64','macos-arm64','macos-x64','linux-x64','linux-arm64','android-arm64'];
     if(!targets.includes(target)){
         fail(`Invalid scaffold target: ${String(target)}. Expected one of ${targets.join(', ')}.`,'ARCANE_USAGE');
     }

package/src/targets/index.mjs

@@ -19,7 +19,7 @@ const DEFINITIONS=[
     },
     {
         id:'portable',displayName:'Portable native application',status:'pairing-required',
-        platforms:['windows','linux'],architectures:['x64','arm64'],formats:['portable'],
+        platforms:['windows','linux','macos'],architectures:['x64','arm64'],formats:['portable'],
         signingModes:['unsigned-local-test'],
         reason:'Portable app payloads use the SDK package provider by default; explicit provider pairing remains available.'
     },
@@ -28,6 +28,16 @@ const DEFINITIONS=[
         platforms:['windows'],architectures:['x64'],formats:['exe'],signingModes:['unsigned-local-test'],
         reason:'Windows output requires an Arcane OS native provider.'
     },
+    {
+        id:'macos-arm64',displayName:'macOS Apple silicon application',status:'pairing-required',
+        platforms:['macos'],architectures:['arm64'],formats:['app'],signingModes:['unsigned-local-test'],
+        reason:'macOS output uses the SDK provider with the selected architecture host asset.'
+    },
+    {
+        id:'macos-x64',displayName:'macOS Intel application',status:'pairing-required',
+        platforms:['macos'],architectures:['x64'],formats:['app'],signingModes:['unsigned-local-test'],
+        reason:'macOS output uses the SDK provider with the selected architecture host asset.'
+    },
     {
         id:'linux-x64',displayName:'Linux x64 executable',status:'pairing-required',
         platforms:['linux'],architectures:['x64'],formats:['deb'],signingModes:['unsigned-local-test'],

package/src/templates/workspace-template.mjs

@@ -84,7 +84,7 @@ export function workspaceTemplate({
         ||(!canonicalSpecifier&&!aliasSpecifier)){
         throw new Error('Invalid scaffold SDK installation authority.');
     }
-    const supportedTargets=['browser','portable','windows-x64','linux-x64','linux-arm64','android-arm64'];
+    const supportedTargets=['browser','portable','windows-x64','macos-arm64','macos-x64','linux-x64','linux-arm64','android-arm64'];
     if(!supportedTargets.includes(target)){
         throw new Error(`Unsupported scaffold target: ${String(target)}.`);
     }
@@ -105,17 +105,18 @@ export function workspaceTemplate({
     const packageInclude=[`${appId}.css`,'index.html'];
     if(native)packageInclude.push('img/icon.png');
     packageInclude.push('manifest.json','modules');
+    const macosTarget=target==='macos-arm64'||target==='macos-x64';
     const nativeGuide=native?`
 ## ${target} native target
 
 This scaffold declares both the browser and ${target} targets and includes the
 required raster application icon.
-Pair it with one explicit Arcane OS checkout:
+${macosTarget?'Use the installed SDK provider and its matching macOS release host asset:':'Pair it with one explicit Arcane OS checkout:'}
 
 \`\`\`sh
-npm exec -- arcane native-doctor --target ${target} --arcane-root "<path-to-Arcane-OS>"
-npm run build -- --arcane-root "<path-to-Arcane-OS>"
-${target==='portable'?'':`npm run run -- --arcane-root "<path-to-Arcane-OS>"\n`}
+npm exec -- arcane native-doctor --target ${target}${macosTarget?'':' --arcane-root "<path-to-Arcane-OS>"'}
+npm run build${macosTarget?'':' -- --arcane-root "<path-to-Arcane-OS>"'}
+${target==='portable'?'':`npm run run${macosTarget?'':' -- --arcane-root "<path-to-Arcane-OS>"'}\n`}
 \`\`\`
 
 The selected Arcane provider must support this target or the command fails without

package/src/toolchain.mjs

@@ -1,6 +1,6 @@
 import Is from 'strong-type';
 import path from 'node:path';
-import {resolvePackageOutputRoot} from './app-layout.mjs';
+import {resolveAppRoot,resolvePackageOutputRoot} from './app-layout.mjs';
 import {readdir,lstat,realpath,mkdir,readFile,writeFile} from 'node:fs/promises';
 import {createWorkspace,initWorkspace} from './scaffold.mjs';
 import {
@@ -17,6 +17,8 @@ import {createPwaArtifacts} from './pwa.mjs';
 import {readInstalledSdkLayout} from './sdk-runtime-layout.mjs';
 import {withWorkspaceOperationLock} from './workspace-operation-lock.mjs';
 import {refreshAppPackageProjection} from './app-descriptor.mjs';
+import {configureDevelopmentLocalAI} from './local-ai/config.mjs';
+import {createDevelopmentLocalAI} from './local-ai/dev.mjs';
 import {
     discoverApps as discoverPackagerApps,
     inspectApp as inspectPackagedApp,
@@ -566,6 +568,11 @@ export async function developApplication(options = {}) {
             onEvent: options.onEvent
         },
         async function refreshDevelopmentWorkspace(workspaceOperationLease) {
+            await configureDevelopmentLocalAI({
+                appRoot: resolveAppRoot(profile.workspaceRoot, profile.config, appId),
+                runtimes: options.localAI,
+                signal: options.signal
+            });
             await refreshAppPackageProjection(
                 {
                     workspaceRoot: profile.workspaceRoot,
@@ -589,7 +596,19 @@ export async function developApplication(options = {}) {
             return current;
         }
     );
-    const server=await startDevServer({
+    const localAIConfig = prepared.descriptor?.native?.localAI;
+    const localAI = localAIConfig?.runtimes.length ? createDevelopmentLocalAI({
+        config: localAIConfig,
+        appRoot: prepared.appRoot,
+        directory: path.join(prepared.appRoot, '.arcane', 'local-ai', 'runtimes'),
+        application: prepared.descriptor,
+        version: prepared.descriptor.version,
+        signal: options.signal,
+        onEvent: options.onEvent
+    }) : undefined;
+    let server;
+    try {
+        server=await startDevServer({
         workspaceRoot:prepared.workspaceRoot,
         appId:prepared.appId,
         mode:'source',
@@ -605,10 +624,19 @@ export async function developApplication(options = {}) {
         tls:options.tls,
         certPath:options.certPath,
         keyPath:options.keyPath,
+        localAI,
         signal:options.signal,
         onEvent:options.onEvent
-    });
-    return {...server,appId:prepared.appId,mode:'source'};
+        });
+    } catch (error) {
+        try {
+            await localAI?.close(error);
+        } catch (closeError) {
+            throw new AggregateError([error, closeError], 'Development startup and local AI shutdown failed.');
+        }
+        throw error;
+    }
+    return {...server,appId:prepared.appId,mode:'source',...(localAI ? {localAI} : {})};
 }
 
 export async function packageApplication(options={}){
@@ -840,7 +868,7 @@ export function assertIntegratedNativeToolchain({
     workspaceMode,workspaceRoot,toolchainRoot,target,providerSource='arcane-checkout'
 }={}){
     if(workspaceMode!=='integrated')return;
-    if(providerSource==='sdk-package'&&target==='portable')return;
+    if(providerSource==='sdk-package'&&['portable','windows-x64','macos-arm64','macos-x64'].includes(target))return;
     if(!is.string(toolchainRoot)||!sameCanonicalPath(workspaceRoot,toolchainRoot)){
         throw new ArcaneError(
             ERROR_CODES.policyDenied,