arcane-os 0.55.0 → 0.57.0

package/schemas/arcane-app.schema.json

@@ -48,6 +48,16 @@
         "pwa": { "$ref": "#/$defs/pwa" },
         "include": { "$ref": "#/$defs/nonemptyPathList" },
         "exclude": { "$ref": "#/$defs/pathList" },
+        "nativeResources": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["include"],
+          "description": "Additional literal application-relative paths for a selected nonbrowser target. Exclude applies only to this additional selection. Native-only files retain their complete original content and do not enter browser document or PWA processing. Omission or an empty include preserves existing selection and output behavior.",
+          "properties": {
+            "include": { "$ref": "#/$defs/pathList" },
+            "exclude": { "$ref": "#/$defs/pathList" }
+          }
+        },
         "shared": {
           "type": "array",
           "minItems": 1,
@@ -109,6 +119,19 @@
           "oneOf": [{ "$ref": "#/$defs/rasterIcon" }, { "type": "null" }]
         },
         "order": { "type": "integer", "minimum": 0 },
+        "services": {
+          "description": "Explicit application-owned Core factory modules from the selected native release. Factories receive authored options first and launch context second.",
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["module"],
+            "properties": {
+              "module": { "$ref": "#/$defs/relativePath" },
+              "options": {}
+            }
+          }
+        },
+        "localAI": { "$ref": "#/$defs/localAI" },
         "bundledApps": {
           "type": "array",
           "uniqueItems": true,
@@ -230,6 +253,47 @@
     }
   ],
   "$defs": {
+    "localAI": {
+      "type": "object",
+      "required": ["runtimes"],
+      "description": "Required Core AI runtimes. Development ensures selected runtimes locally; native builds bundle their upstream runtime distributions. Model selection remains application-owned.",
+      "properties": {
+        "runtimes": {
+          "type": "array",
+          "items": {
+            "oneOf": [
+              { "enum": ["llama.cpp", "ollama"] },
+              {
+                "type": "object",
+                "required": ["id"],
+                "properties": {
+                  "id": { "enum": ["llama.cpp", "ollama"] },
+                  "version": { "type": "string" },
+                  "url": { "type": "string" }
+                }
+              }
+            ]
+          }
+        },
+        "llamaCpp": {
+          "type": "object",
+          "properties": {
+            "url": { "type": "string" },
+            "model": { "type": "string" },
+            "modelsDirectory": { "type": "string" },
+            "args": { "type": "array", "items": { "type": "string" } }
+          }
+        },
+        "ollama": {
+          "type": "object",
+          "properties": {
+            "url": { "type": "string" },
+            "modelsDirectory": { "type": "string" },
+            "args": { "type": "array", "items": { "type": "string" } }
+          }
+        }
+      }
+    },
     "pwa": {
       "type": "object",
       "additionalProperties": false,

package/schemas/arcane-package.schema.json

@@ -57,6 +57,9 @@
     "localAIModelPolicy": {
       "$ref": "#/$defs/localAIModelPolicy"
     },
+    "localAI": {
+      "$ref": "#/$defs/localAI"
+    },
     "pwa": {
       "$ref": "#/$defs/pwa"
     },
@@ -88,6 +91,16 @@
     "exclude": {
       "$ref": "#/$defs/pathList"
     },
+    "nativeResources": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["include"],
+      "description": "Additional literal application-relative paths for a selected nonbrowser target. Exclude applies only to this additional selection. Native-only files retain their complete original content and do not enter browser document or PWA processing. Omission or an empty include preserves existing selection and output behavior.",
+      "properties": {
+        "include": { "$ref": "#/$defs/pathList" },
+        "exclude": { "$ref": "#/$defs/pathList" }
+      }
+    },
     "shared": {
       "type": "array",
       "uniqueItems": true,
@@ -134,6 +147,47 @@
     }
   ],
   "$defs": {
+    "localAI": {
+      "type": "object",
+      "required": ["runtimes"],
+      "description": "Required Core AI runtimes. Development ensures selected runtimes locally; native builds bundle their upstream runtime distributions. Model selection remains application-owned.",
+      "properties": {
+        "runtimes": {
+          "type": "array",
+          "items": {
+            "oneOf": [
+              { "enum": ["llama.cpp", "ollama"] },
+              {
+                "type": "object",
+                "required": ["id"],
+                "properties": {
+                  "id": { "enum": ["llama.cpp", "ollama"] },
+                  "version": { "type": "string" },
+                  "url": { "type": "string" }
+                }
+              }
+            ]
+          }
+        },
+        "llamaCpp": {
+          "type": "object",
+          "properties": {
+            "url": { "type": "string" },
+            "model": { "type": "string" },
+            "modelsDirectory": { "type": "string" },
+            "args": { "type": "array", "items": { "type": "string" } }
+          }
+        },
+        "ollama": {
+          "type": "object",
+          "properties": {
+            "url": { "type": "string" },
+            "modelsDirectory": { "type": "string" },
+            "args": { "type": "array", "items": { "type": "string" } }
+          }
+        }
+      }
+    },
     "pwa": {
       "type": "object",
       "additionalProperties": false,

package/src/app-descriptor.mjs

@@ -5,6 +5,7 @@ import {readFile, writeFile} from 'node:fs/promises';
 import path from 'node:path';
 import {throwIfAborted} from './errors.mjs';
 import {normalizePwaConfig} from './pwa.mjs';
+import {normalizeLocalAIConfig} from './local-ai/config.mjs';
 import {
     ARCANE_MACHINE_BUNDLE_VERSION,
     ARCANE_PROTOCOL,
@@ -111,13 +112,21 @@ function validateLocalAIModelPolicy(value,label){
 
 function validatePackage(value,appId){
     assertOnlyKeys(value,new Set([
-        'entry','strategy','include','exclude','shared','adapter','localAIModelPolicy','pwa','documents'
+        'entry','strategy','include','exclude','shared','adapter','localAIModelPolicy','pwa','documents','nativeResources'
     ]),'descriptor.package');
     const entry=normalizeRelativePath(value.entry,'descriptor.package.entry');
     const documents=normalizeAppDocuments(value.documents,'descriptor.package.documents');
     if(!['static','adapter'].includes(value.strategy))fail('descriptor.package.strategy must be static or adapter.');
     const include=relativePaths(value.include,'descriptor.package.include',{required:true});
     const exclude=relativePaths(value.exclude??[],'descriptor.package.exclude');
+    let nativeResources;
+    if(value.nativeResources!==undefined){
+        assertOnlyKeys(value.nativeResources,new Set(['include','exclude']),'descriptor.package.nativeResources');
+        nativeResources={
+            include:relativePaths(value.nativeResources.include,'descriptor.package.nativeResources.include'),
+            exclude:relativePaths(value.nativeResources.exclude??[],'descriptor.package.nativeResources.exclude')
+        };
+    }
     if(!include.some(candidate=>entry===candidate||entry.startsWith(`${candidate}/`))){
         fail('descriptor.package.entry must be covered by descriptor.package.include.');
     }
@@ -140,6 +149,7 @@ function validatePackage(value,appId){
         strategy:value.strategy,
         include,
         exclude,
+        ...(nativeResources===undefined?{}:{nativeResources}),
         shared,
         ...(value.pwa===undefined?{}:{pwa:normalizePwaConfig(value.pwa)}),
         ...(adapter?{adapter}:{}),
@@ -226,7 +236,7 @@ function validateDocumentCatalog(value){
 }
 
 function validateNative(value,appId){
-    assertOnlyKeys(value,new Set(['type','icon','order','bundledApps','documentCatalog']),'descriptor.native');
+    assertOnlyKeys(value,new Set(['type','icon','order','bundledApps','documentCatalog','localAI','services']),'descriptor.native');
     if(!NATIVE_TYPES.has(value.type))fail('descriptor.native.type is unsupported.');
     const icon=value.icon===null?null:normalizeRelativePath(value.icon,'descriptor.native.icon');
     if(!is.integer(value.order)||value.order<0){
@@ -236,11 +246,21 @@ function validateNative(value,appId){
         pattern:APP_ID_PATTERN
     });
     const documentCatalog=validateDocumentCatalog(value.documentCatalog);
+    let services;
+    if(value.services!==undefined){
+        if(!is.array(value.services))fail('descriptor.native.services must be an array.');
+        services=value.services.map(function nativeService(service,index){
+            if(!isObject(service))fail(`descriptor.native.services[${index}] must be an object.`);
+            return {...service,module:normalizeRelativePath(service.module,`descriptor.native.services[${index}].module`)};
+        });
+    }
     return completeValue({
         type:value.type,
         icon,
         order:value.order,
         bundledApps,
+        ...(services===undefined?{}:{services}),
+        ...(value.localAI===undefined?{}:{localAI:normalizeLocalAIConfig(value.localAI)}),
         ...(documentCatalog?{documentCatalog}:{})
     });
 }
@@ -328,9 +348,14 @@ export function projectPackageManifest(descriptor){
             mediaOrigins:[...value.security.mediaOrigins]
         }}:{}),
         ...(value.package.localAIModelPolicy?{localAIModelPolicy:value.package.localAIModelPolicy}:{}),
+        ...(value.native.localAI===undefined?{}:{localAI:value.native.localAI}),
         ...(value.package.pwa===undefined?{}:{pwa:value.package.pwa}),
         include:[...value.package.include],
         exclude:[...value.package.exclude],
+        ...(value.package.nativeResources===undefined?{}:{nativeResources:{
+            include:[...value.package.nativeResources.include],
+            exclude:[...value.package.nativeResources.exclude]
+        }}),
         shared:[...value.package.shared],
         ...(value.package.adapter?{adapter:value.package.adapter}:{})
     };
@@ -369,6 +394,8 @@ export function projectNativeDescriptor(descriptor,{source}={}){
         }}:{}),
         ...(value.native.bundledApps.length?{bundledApps:[...value.native.bundledApps]}:{}),
         ...(value.native.documentCatalog?{documentCatalog:value.native.documentCatalog}:{}),
+        ...(value.native.services===undefined?{}:{services:value.native.services}),
+        ...(value.native.localAI===undefined?{}:{localAI:value.native.localAI}),
         include:[...value.package.include]
     };
 }
@@ -391,6 +418,10 @@ function synthesizedDescriptor(packageManifest,nativeDescriptor){
             ...(packageManifest.pwa===undefined?{}:{pwa:packageManifest.pwa}),
             include:[...packageManifest.include],
             exclude:[...(packageManifest.exclude??[])],
+            ...(packageManifest.nativeResources===undefined?{}:{nativeResources:{
+                include:[...packageManifest.nativeResources.include],
+                exclude:[...(packageManifest.nativeResources.exclude??[])]
+            }}),
             shared:[...packageManifest.shared],
             ...(packageManifest.adapter?{adapter:packageManifest.adapter}:{})
         },
@@ -408,6 +439,8 @@ function synthesizedDescriptor(packageManifest,nativeDescriptor){
             icon:native.icon??null,
             order:is.integer(native.order)?native.order:100,
             bundledApps:[...(native.bundledApps??[])],
+            ...(native.services===undefined?{}:{services:native.services}),
+            ...((packageManifest.localAI??native.localAI)===undefined?{}:{localAI:packageManifest.localAI??native.localAI}),
             ...(native.documentCatalog?{documentCatalog:native.documentCatalog}:{})
         },
         requirements:{

package/src/app-layout.mjs

@@ -9,8 +9,12 @@ export function resolveAppRoot(workspaceRoot, config, appId) {
     return path.resolve(workspaceRoot, appRelativeRoot(config, appId));
 }
 
-export function resolvePackageOutputRoot(workspaceRoot, config, app) {
-    return path.resolve(workspaceRoot, app.outputDirectory ?? `${config.distRoot}/${app.id}`);
+export function resolvePackageOutputRoot(workspaceRoot, config, app, {target='browser', outputDirectory}={}) {
+    const nativeSelection=target!=='browser'&&app.nativeResources?.include.length>0;
+    const selectedDirectory=outputDirectory??(nativeSelection
+        ?`${config.distRoot}/.native/${target}/${app.id}`
+        :app.outputDirectory??`${config.distRoot}/${app.id}`);
+    return path.resolve(workspaceRoot,selectedDirectory);
 }
 
 export function appBaseHref(workspaceRoot, appRoot, document = 'index.html') {

package/src/cli/main.mjs

@@ -16,6 +16,7 @@ const VALUE_OPTIONS=new Set([
     'app',
     'apps-root',
     'sdk-runtime-source',
+    'local-ai',
     'arcane-root',
     'host',
     'port',
@@ -66,7 +67,7 @@ Usage:
   ${CLI_NAME} upgrade [--workspace <directory>] [--app <id>]
   ${CLI_NAME} doctor [--workspace <directory>] [--arcane-root <directory>]
   ${CLI_NAME} import-map [--workspace <directory>] [--app <id>]
-  ${CLI_NAME} dev [--app <id>] [--public] [--http | --https] [--cert <pem>] [--key <pem>] [--host <address>] [--port 8000] [--http-port 0] [--sdk-runtime-source <sdk-root>]
+  ${CLI_NAME} dev [--app <id>] [--public] [--http | --https] [--cert <pem>] [--key <pem>] [--host <address>] [--port 8000] [--http-port 0] [--sdk-runtime-source <sdk-root>] [--local-ai llama.cpp,ollama]
   ${CLI_NAME} test [--app <id>] [--scope app]
   ${CLI_NAME} test --scope shared --test-file <repo-relative.test.mjs>
   ${CLI_NAME} check [--app <id>] [--scope app] [--skip-tests]
@@ -97,6 +98,7 @@ Development:
   --host <address>               Override the bind address; takes precedence over --public.
   --http-port <port>             Browser dev/run HTTP redirect port; 0 selects an available port (default).
   --sdk-runtime-source <sdk-root>  Dev-only live SDK checkout; omitted preserves the workspace runtime mode.
+  --local-ai <runtimes>          Add required Core runtimes to app config and ensure them for development.
 
 Global:
   --workspace <directory>       Select an external or integrated Arcane workspace.
@@ -450,6 +452,9 @@ function operationOptions(command,parsed,cwd){
     if(values['sdk-runtime-source']!==undefined&&command!=='dev'){
         usage('--sdk-runtime-source is supported only by dev.');
     }
+    if(values['local-ai']!==undefined&&command!=='dev'){
+        usage('--local-ai is supported only by dev.');
+    }
     if(flags.has('public')&&command!=='dev'){
         usage('--public is supported only by dev.');
     }
@@ -546,6 +551,7 @@ function operationOptions(command,parsed,cwd){
             ...browserServerOptions,
             host:values.host??(flags.has('public')?'0.0.0.0':'127.0.0.1'),
             port:readPort(values.port,8000),
+            ...(values['local-ai']===undefined?{}:{localAI:values['local-ai']}),
             ...(values['sdk-runtime-source']===undefined?{}:{
                 sdkRuntimeSourceRoot:path.resolve(cwd,values['sdk-runtime-source'])
             })
@@ -811,7 +817,7 @@ async function pairNativeProvider(command,options,loadProvider,{signal,onEvent}=
         usage(`${command} requires one native target.`);
     }
     const targetRequest=createNativeTargetRequest(options);
-    if(!options.arcaneRoot&&options.target!=='portable'){
+    if(!options.arcaneRoot&&!['portable','windows-x64'].includes(options.target)){
         usage(`${command} for target ${options.target} requires --arcane-root <directory>.`);
     }
     const loaded=await loadProvider({

package/src/core/host.mjs

@@ -1,6 +1,29 @@
+import {readFile} from 'node:fs/promises';
+import Is from 'strong-type';
 import {createCoreRuntime} from './runtime.mjs';
 import {startCoreStdio} from './stdio.mjs';
 
+const is = new Is(false);
+
+/**
+ * Read only the explicitly supplied --arcane-launch-config filename.
+ * Return the complete JSON object for the service factories' second argument;
+ * field meanings belong to the launch owner and individual services.
+ */
+export async function readCoreLaunchContext({argv = process.argv.slice(2)} = {}) {
+    const flag = argv.indexOf('--arcane-launch-config');
+    if (flag === -1) return {};
+    const filename = argv[flag + 1];
+    if (filename === undefined || filename === '') {
+        throw new TypeError('--arcane-launch-config requires a filename.');
+    }
+    const context = JSON.parse(await readFile(filename, 'utf8'));
+    if (context === null || !is.object(context) || is.array(context)) {
+        throw new TypeError('Core launch configuration must be a JSON object.');
+    }
+    return context;
+}
+
 /** Compose app services with the shared dispatcher and draining transport. */
 export function startCoreHost({application, version, services = [], input, output, onError, signal} = {}) {
     const runtime = createCoreRuntime({application, version, services});

package/src/core/hosts/arcane-core-loader.cjs

@@ -0,0 +1,2 @@
+// This ordinary filesystem module retains Node's asynchronous ESM loader.
+module.exports = import('./arcane-core.mjs');