arcane-os 0.63.0 → 0.64.0

package/src/core/repositories.mjs

@@ -0,0 +1,210 @@
+import {mkdir, readdir} from 'node:fs/promises';
+import {homedir} from 'node:os';
+import path from 'node:path';
+import Is from 'strong-type';
+import {ArcaneError, throwIfAborted} from '../errors.mjs';
+import {runProcess} from '../process.mjs';
+import {repositoryPull, repositoryPush, repositoryStatus} from '../repository.mjs';
+
+const is = new Is(false);
+const directoryOperations = new Map();
+
+/** Resolve persistent native data without creating or migrating anything. */
+export function resolveArcaneDataPaths({dataRoot} = {}) {
+    let root = dataRoot;
+    if (root === undefined) {
+        const home = homedir();
+        switch (process.platform) {
+            case 'win32':
+                root = path.join(process.env.LOCALAPPDATA || path.join(home, 'AppData', 'Local'), 'ArcaneData');
+                break;
+            case 'darwin':
+                root = path.join(home, 'Library', 'Application Support', 'ArcaneData');
+                break;
+            case 'linux': {
+                const xdg = process.env.XDG_DATA_HOME;
+                const base = xdg && path.isAbsolute(xdg) ? xdg : path.join(home, '.local', 'share');
+                root = path.join(base, 'ArcaneData');
+                break;
+            }
+            default:
+                throw new ArcaneError(
+                    'ARCANE_DATA_ROOT_REQUIRED',
+                    'This native host must supply its persistent ArcaneData directory through dataRoot.'
+                );
+        }
+    }
+    requireString(root, 'dataRoot');
+    const resolved = path.resolve(root);
+    return {dataRoot: resolved, repositoriesRoot: path.join(resolved, 'Repos')};
+}
+
+/** One connected checkout, composed into an application's own Core service. */
+export function createRepositoryWorkspace(
+    {name, directory, dataRoot, remote, branch, onEvent, run = runProcess} = {}
+) {
+    let selected = directory;
+    if (selected === undefined) {
+        requireString(name, 'name');
+        if (name === '.' || name === '..' || /[/\\]/u.test(name)) {
+            throw new TypeError('name must be one directory name; use directory for an explicit repository path.');
+        }
+        selected = path.join(resolveArcaneDataPaths({dataRoot}).repositoriesRoot, name);
+    }
+    requireString(selected, 'directory');
+    if (remote !== undefined) requireString(remote, 'remote');
+    if (branch !== undefined) requireString(branch, 'branch');
+    if (!is.function(run)) throw new TypeError('run must implement the SDK process adapter.');
+    const repositoryDirectory = path.resolve(selected);
+    const pending = new Set();
+    let opened = false;
+    let closing = null;
+
+    async function prepare(signal) {
+        throwIfAborted(signal);
+        if (opened) return {directory: repositoryDirectory, cloned: false};
+        let entries;
+        try {
+            entries = await readdir(repositoryDirectory);
+        } catch (error) {
+            if (error.code !== 'ENOENT') throw error;
+            entries = [];
+        }
+        throwIfAborted(signal);
+        if (entries.length) {
+            // A parent checkout or a bare object cache is not this connection's
+            // working root. Inspection never changes an existing destination.
+            const result = await run(
+                'git',
+                ['rev-parse', '--is-inside-work-tree', '--show-prefix'],
+                {cwd: repositoryDirectory, signal, onEvent}
+            );
+            throwIfAborted(signal);
+            const [inside, prefix] = result.stdout.split(/\r?\n/u);
+            if (inside !== 'true' || prefix !== '') {
+                throw new ArcaneError(
+                    'ARCANE_REPOSITORY_DIRECTORY_INVALID',
+                    'The selected nonempty directory is not a Git working repository root.',
+                    {details: result}
+                );
+            }
+            opened = true;
+            return {directory: repositoryDirectory, cloned: false};
+        }
+        requireString(remote, 'remote');
+        await mkdir(path.dirname(repositoryDirectory), {recursive: true});
+        throwIfAborted(signal);
+        const arguments_ = ['clone', '--progress'];
+        if (branch !== undefined) arguments_.push('--branch', branch);
+        arguments_.push('--', remote, repositoryDirectory);
+        const result = await run(
+            'git',
+            arguments_,
+            {cwd: path.dirname(repositoryDirectory), signal, onEvent}
+        );
+        throwIfAborted(signal);
+        opened = true;
+        return {directory: repositoryDirectory, cloned: true, stdout: result.stdout, stderr: result.stderr};
+    }
+
+    function accept(operation, signal) {
+        try {
+            throwIfAborted(signal);
+            if (closing) throw new ArcaneError('CORE_CLOSING', 'The repository workspace is closing.');
+        } catch (error) {
+            return Promise.reject(error);
+        }
+        const result = orderDirectoryOperation(
+            repositoryDirectory,
+            async function runRepositoryOperation() {
+                throwIfAborted(signal);
+                return operation();
+            }
+        );
+        pending.add(result);
+        function settled() {
+            pending.delete(result);
+        }
+        result.then(settled, settled);
+        return result;
+    }
+
+    function open({signal} = {}) {
+        return accept(
+            function openRepository() {
+                return prepare(signal);
+            },
+            signal
+        );
+    }
+
+    function status({signal} = {}) {
+        return accept(
+            async function readRepositoryStatus() {
+                await prepare(signal);
+                return repositoryStatus({workspaceRoot: repositoryDirectory, signal, onEvent, run});
+            },
+            signal
+        );
+    }
+
+    function pull({signal} = {}) {
+        return accept(
+            async function pullRepository() {
+                await prepare(signal);
+                return repositoryPull({workspaceRoot: repositoryDirectory, signal, onEvent, run});
+            },
+            signal
+        );
+    }
+
+    function push({signal} = {}) {
+        return accept(
+            async function pushRepository() {
+                await prepare(signal);
+                return repositoryPush({workspaceRoot: repositoryDirectory, signal, onEvent, run});
+            },
+            signal
+        );
+    }
+
+    function close() {
+        if (!closing) {
+            closing = Promise.allSettled([...pending]).then(
+                function operationsDrained(results) {
+                    const failures = results.filter(
+                        function failed(result) {
+                            return result.status === 'rejected';
+                        }
+                    ).map(
+                        function reason(result) {
+                            return result.reason;
+                        }
+                    );
+                    if (failures.length) throw new AggregateError(failures, 'Repository operations failed while draining.');
+                }
+            );
+        }
+        return closing;
+    }
+
+    return {directory: repositoryDirectory, open, status, pull, push, close, drain: close, dispose: close};
+}
+
+function requireString(value, name) {
+    if (!is.string(value) || value === '') throw new TypeError(`${name} must be a nonempty string.`);
+}
+
+function orderDirectoryOperation(directory, operation) {
+    const key = process.platform === 'win32' ? directory.toLowerCase() : directory;
+    const previous = directoryOperations.get(key) ?? Promise.resolve();
+    const result = previous.then(operation, operation);
+    function releaseQueue() {
+        if (directoryOperations.get(key) === tail) directoryOperations.delete(key);
+    }
+    // Only the scheduling tail settles successfully after an error. Each caller
+    // retains its complete failure; a later operation can retry the same path.
+    const tail = result.then(releaseQueue, releaseQueue);
+    directoryOperations.set(key, tail);
+    return result;
+}

package/src/core/services/speech.mjs

@@ -196,6 +196,7 @@ export function createSpeechService({stt, tts, signal} = {}) {
                 parameters,
                 {
                     signal: operationSignal,
+                    requestId: request.requestId,
                     onProgress(progress) {
                         if (!operationSignal.aborted) {
                             request.emit?.(

package/src/local-ai/config.mjs

@@ -4,9 +4,11 @@ import Is from 'strong-type';
 import {ArcaneError, ERROR_CODES, throwIfAborted} from '../errors.mjs';
 import {SD14_MODEL} from './image-models/sd14.mjs';
 import {FLUX2_KLEIN_4B_MODEL} from './image-models/flux.mjs';
+import {SDXL_BASE_1_0_MODEL} from './image-models/sdxl.mjs';
+import {normalizeWhisperRuntimeRequirement} from './whisper/config.mjs';
 
 const is = new Is(false);
-export const LOCAL_AI_RUNTIME_IDS = ['llama.cpp', 'ollama', 'onnx', 'stable-diffusion.cpp'];
+export const LOCAL_AI_RUNTIME_IDS = ['llama.cpp', 'ollama', 'onnx', 'stable-diffusion.cpp', 'whisper.cpp'];
 
 /** Image requirements describe assets without acquiring or loading a model. */
 export function normalizeImageRuntimeRequirement(record) {
@@ -20,9 +22,10 @@ export function normalizeImageRuntimeRequirement(record) {
     const models = (record.models ?? []).map(
         function selectedImageModel(value) {
             const model = value === 'sd14' ? SD14_MODEL
-                : value === 'flux2-klein-4b' ? FLUX2_KLEIN_4B_MODEL : value;
+                : value === 'flux2-klein-4b' ? FLUX2_KLEIN_4B_MODEL
+                : value === 'sdxl-base-1.0' ? SDXL_BASE_1_0_MODEL : value;
             if (!model || !is.object(model) || is.array(model) || !is.string(model.id) || !model.id) {
-                throw new ArcaneError(ERROR_CODES.usage, 'An image model needs a descriptor with an id, or a built-in model ID (sd14 or flux2-klein-4b).');
+                throw new ArcaneError(ERROR_CODES.usage, 'An image model needs a descriptor with an id, or a built-in model ID (sd14, flux2-klein-4b, or sdxl-base-1.0).');
             }
             if (!model.resources || !is.object(model.resources) || is.array(model.resources)) {
                 throw new ArcaneError(ERROR_CODES.usage, `Image model ${model.id} needs resources keyed by model role.`);
@@ -59,6 +62,7 @@ export function normalizeLocalAIConfig(value) {
             throw new ArcaneError(ERROR_CODES.usage, `Unknown local AI runtime: ${String(record?.id ?? item)}.`);
         }
         if (record.id === 'stable-diffusion.cpp') return normalizeImageRuntimeRequirement(record);
+        if (record.id === 'whisper.cpp') return normalizeWhisperRuntimeRequirement(record);
         return {...record};
     });
     return {...value, runtimes};

package/src/local-ai/dev.mjs

@@ -1,12 +1,15 @@
+import path from 'node:path';
 import Is from 'strong-type';
 import {createCoreRuntime} from '../core/runtime.mjs';
 import {createLocalAIService} from '../core/services/local-ai.mjs';
 import {createLocalImageService} from '../core/services/image.mjs';
 import {createModelAssetService} from '../core/services/model-assets.mjs';
+import {createSpeechService} from '../core/services/speech.mjs';
 import {CORE_PROTOCOL, CoreError, serializeCoreError} from '../../browser-runtime/core/contracts.mjs';
 import {normalizeLocalAIConfig} from './config.mjs';
 import {discoverLocalAIRuntimes} from './discover.mjs';
 import {ensureLocalAIRuntimes} from './install.mjs';
+import {createWhisperRuntime} from './whisper/index.mjs';
 
 const is = new Is(false);
 
@@ -84,6 +87,7 @@ export function createDevelopmentLocalAI({config, appRoot, directory, applicatio
     let runtime;
     let service;
     let imageService;
+    let speechService;
     let modelAssets;
     let stopFrames;
     let preparationError = null;
@@ -162,6 +166,7 @@ export function createDevelopmentLocalAI({config, appRoot, directory, applicatio
         for (const record of current.services) writeFrame(connection, event('core.service.state', record));
         writeFrame(connection, event('localai.state', service.current()));
         if (imageService) writeFrame(connection, event('image.state', imageService.current()));
+        if (speechService) writeFrame(connection, event('speech.state', speechService.current()));
         if (modelAssets) writeFrame(connection, event('modelAssets.state', modelAssets.current()));
     }
 
@@ -170,7 +175,7 @@ export function createDevelopmentLocalAI({config, appRoot, directory, applicatio
         const localConfig = {
             ...selected,
             runtimes: selected.runtimes.filter(function selectedChatRuntime(requirement) {
-                return requirement.id !== 'stable-diffusion.cpp';
+                return requirement.id !== 'stable-diffusion.cpp' && requirement.id !== 'whisper.cpp';
             })
         };
         service = createLocalAIService(
@@ -203,6 +208,30 @@ export function createDevelopmentLocalAI({config, appRoot, directory, applicatio
             );
             services.push(modelAssets, imageService);
         }
+        const whisperRequirement = selected.runtimes.find(
+            function selectedWhisperRuntime(requirement) {
+                return requirement.id === 'whisper.cpp';
+            }
+        );
+        if (whisperRequirement) {
+            const stt = createWhisperRuntime(
+                {
+                    modelId: whisperRequirement.modelId,
+                    temporaryDirectory: path.join(appRoot, '.arcane', 'speech', 'whisper'),
+                    onEvent,
+                    async prepare({signal, onEvent: report}) {
+                        const installed = await ensureLocalAIRuntimes(
+                            {runtimes: [whisperRequirement], directory, signal, onEvent: report}
+                        );
+                        return installed[0];
+                    }
+                }
+            );
+            speechService = createSpeechService(
+                {stt, signal: operationSignal}
+            );
+            services.push(speechService);
+        }
         runtime = createCoreRuntime({application, version, services});
         stopFrames = runtime.onFrame(routeFrame);
         runtime.start();
@@ -387,7 +416,8 @@ export function createDevelopmentLocalAI({config, appRoot, directory, applicatio
         return {state: closed ? 'closed' : preparationError ? 'error' : runtime ? 'ready' : 'preparing',
             error: preparationError ? serializeCoreError(preparationError) : null,
             core: runtime?.current() ?? null, localAI: service?.current() ?? null,
-            image: imageService?.current() ?? null};
+            image: imageService?.current() ?? null,
+            speech: speechService?.current() ?? null};
     }
 
     function close() {

package/src/local-ai/image-library.mjs

@@ -18,6 +18,15 @@ export function createImageLibrary(
 ) {
     const requireBinding = createRequire(bindingModulePath);
     const koffi = requireBinding(bindingModulePath);
+    const configuration = koffi.config();
+    // Async inference needs the normal native stack before Koffi creates its pools.
+    if (configuration.async_stack_size < configuration.sync_stack_size) {
+        koffi.config(
+            {
+                async_stack_size: configuration.sync_stack_size
+            }
+        );
+    }
     const library = loadLibrary(libraryPath);
     const backendDirectory = dirname(libraryPath);
     let backendLibrary;

package/src/local-ai/image-models/sdxl.mjs

@@ -0,0 +1,18 @@
+/** Official complete SDXL checkpoint; acquisition belongs to the model asset owner. */
+export const SDXL_BASE_1_0_MODEL = {
+    id: 'sdxl-base-1.0',
+    name: 'SDXL Base 1.0',
+    family: 'sdxl',
+    resources: {
+        model: {
+            url: 'https://huggingface.co/stabilityai/stable-diffusion-xl-base-1.0/resolve/462165984030d82259a11f4367a4eed129e94a7b/sd_xl_base_1.0.safetensors',
+            filename: 'sd_xl_base_1.0.safetensors'
+        }
+    },
+    context: {},
+    defaults: {
+        width: 1024,
+        height: 1024
+    },
+    operations: ['txt2img']
+};

package/src/local-ai/install.mjs

@@ -10,6 +10,8 @@ import {createEventQueue} from '../event-queue.mjs';
 import {runProcess} from '../process.mjs';
 import {extractLocalAIArchive} from './archive.mjs';
 import {normalizeImageRuntimeRequirement} from './config.mjs';
+import {normalizeWhisperRuntimeRequirement} from './whisper/config.mjs';
+import {bundledWhisperRuntime, installedWhisperRuntime, installWhisperDistribution, whisperRuntimeSelection} from './whisper/install.mjs';
 
 const is=new Is(false);
 const installations=new Map();
@@ -21,11 +23,15 @@ function selectRuntimes(runtimes){
     const selected=new Map();
     for(const item of runtimes){
         const requirement=is.string(item)?{id:item}:item;
-        const runtime=requirement?.id==='stable-diffusion.cpp'?normalizeImageRuntimeRequirement(requirement):requirement;
-        if(!runtime||!['llama.cpp','ollama','nemo-speech','onnx','stable-diffusion.cpp'].includes(runtime.id)){
+        const runtime=requirement?.id==='stable-diffusion.cpp'?normalizeImageRuntimeRequirement(requirement)
+            :requirement?.id==='whisper.cpp'?normalizeWhisperRuntimeRequirement(requirement):requirement;
+        if(!runtime||!['llama.cpp','ollama','nemo-speech','onnx','stable-diffusion.cpp','whisper.cpp'].includes(runtime.id)){
             throw new ArcaneError(ERROR_CODES.targetUnavailable,`Local AI runtime installation is unavailable for ${String(runtime?.id)}.`);
         }
         const prior=selected.get(runtime.id);
+        if(prior&&runtime.id==='whisper.cpp'&&whisperRuntimeSelection(prior)!==whisperRuntimeSelection(runtime)){
+            throw new ArcaneError(ERROR_CODES.usage,'Select one complete whisper.cpp runtime and model requirement for this operation.');
+        }
         if(prior&&(prior.version!==runtime.version||prior.url!==runtime.url||(runtime.id==='stable-diffusion.cpp'&&prior.backend!==runtime.backend))){
             throw new ArcaneError(ERROR_CODES.usage,`Select one ${runtime.id} runtime version and URL for this operation.`);
         }
@@ -351,7 +357,7 @@ function bundledImageModelResource(resource, descriptor, model, role, runtimeRoo
     return bundled;
 }
 
-async function installedRuntime(base,runtime,platform,architecture,signal){
+async function installedRuntime(base,runtime,platform,architecture,signal,reuseWhisper=false){
     let entries;
     try{
         entries=await readdir(base,{withFileTypes:true});
@@ -374,9 +380,19 @@ async function installedRuntime(base,runtime,platform,architecture,signal){
         }
         if(installation.requestVersion!==(runtime.version??null)||installation.requestUrl!==(runtime.url??null))continue;
         if (runtime.id === 'stable-diffusion.cpp' && installation.requestBackend !== runtime.backend) continue;
+        let whisperRequirement;
+        if (runtime.id === 'whisper.cpp') {
+            if (!installation.requestWhisper) continue;
+            whisperRequirement = JSON.parse(installation.requestWhisper);
+            if (whisperRuntimeSelection(whisperRequirement, !reuseWhisper) !== whisperRuntimeSelection(runtime, !reuseWhisper)) continue;
+        }
         const record=installation.runtime;
         if(record?.id!==runtime.id||record.platform!==platform||record.architecture!==architecture)continue;
         try{
+            if(runtime.id==='whisper.cpp'){
+                if(await installedWhisperRuntime(record,signal,!reuseWhisper))return reuseWhisper?{runtime:record,requirement:whisperRequirement}:record;
+                continue;
+            }
             if (runtime.id === 'stable-diffusion.cpp') {
                 const locations = [record.libraryPath, record.bindingModulePath];
                 if (!Array.isArray(record.variants) || record.variants.length === 0) continue;
@@ -524,10 +540,11 @@ async function installRuntime(runtime,{directory,platform,architecture,signal,on
         await onEvent({type:'local-ai.install.available',message:`${runtime.id} ${installed.version} is already installed.`,data:installed});
         return installed;
     }
+    const reusableWhisper=runtime.id==='whisper.cpp'?await installedRuntime(base,runtime,platform,architecture,signal,true):null;
     if(runtime.id==='onnx'&&(!['win32','linux','darwin'].includes(platform)||!['x64','arm64'].includes(architecture))){
         throw new ArcaneError(ERROR_CODES.targetUnavailable,`onnxruntime-node has no supported ${platform}/${architecture} CPU runtime.`);
     }
-    const release=runtime.id==='onnx'?null:await selectRelease(runtime,platform,architecture,signal);
+    const release=['onnx','whisper.cpp'].includes(runtime.id)?null:await selectRelease(runtime,platform,architecture,signal);
     throwIfAborted(signal);
     await mkdir(base,{recursive:true});
     const attempt=await mkdtemp(path.join(base,'install-'));
@@ -538,6 +555,8 @@ async function installRuntime(runtime,{directory,platform,architecture,signal,on
         let locations;
         if(runtime.id==='onnx'){
             locations=await installONNXPackage(runtime,{root,directory,platform,architecture,signal,onEvent});
+        } else if (runtime.id === 'whisper.cpp') {
+            locations = await installWhisperDistribution(runtime, {root, directory, platform, architecture, signal, onEvent, upstreamResponse, reusable: reusableWhisper});
         } else if (runtime.id === 'stable-diffusion.cpp') {
             locations = await installImageDistribution(
                 release,
@@ -556,7 +575,7 @@ async function installRuntime(runtime,{directory,platform,architecture,signal,on
         const record={id:runtime.id,platform,architecture,root,...locations,...(runtime.version?{requestedVersion:runtime.version}:{})};
         throwIfAborted(signal);
         if(archive)await unlink(archive);
-        await writeFile(path.join(attempt,'installation.json'),`${JSON.stringify({requestVersion:runtime.version??null,requestUrl:runtime.url??null,...(runtime.id==='stable-diffusion.cpp'?{requestBackend:runtime.backend}:{}),runtime:record},null,2)}\n`,{flag:'wx',signal});
+        await writeFile(path.join(attempt,'installation.json'),`${JSON.stringify({requestVersion:runtime.version??null,requestUrl:runtime.url??null,...(runtime.id==='stable-diffusion.cpp'?{requestBackend:runtime.backend}:{}),...(runtime.id==='whisper.cpp'?{requestWhisper:whisperRuntimeSelection(runtime)}:{}),runtime:record},null,2)}\n`,{flag:'wx',signal});
         completed=true;
         await onEvent({type:'local-ai.install.completed',message:`${runtime.id} ${record.version} is available.`,data:record});
         return record;
@@ -576,7 +595,7 @@ async function installRuntime(runtime,{directory,platform,architecture,signal,on
 
 function shareInstallation(runtime,options){
     throwIfAborted(options.signal);
-    const key=JSON.stringify([options.directory,options.platform,options.architecture,runtime.id,runtime.version??null,runtime.url??null,runtime.id==='stable-diffusion.cpp'?runtime.backend:null]);
+    const key=JSON.stringify([options.directory,options.platform,options.architecture,runtime.id,runtime.version??null,runtime.url??null,runtime.id==='stable-diffusion.cpp'?runtime.backend:null,runtime.id==='whisper.cpp'?whisperRuntimeSelection(runtime):null]);
     let entry=installations.get(key);
     if(entry?.controller.signal.aborted){
         // The prior cancelled attempt owns its cleanup. A later request waits
@@ -725,7 +744,7 @@ export async function bundleLocalAIRuntimes({runtimes=[],directory,outputRoot,pl
         const files=[];
         const relative=`runtime/local-ai/${runtime.id}`;
         const destination=path.join(root,relative);
-        const bundled={...runtime,root:relative};
+        const bundled=runtime.id==='whisper.cpp'?bundledWhisperRuntime(runtime,relative):{...runtime,root:relative};
         for(const field of ['executable','modulePath','includeDirectory','libraryDirectory','binaryDirectory','cmakeDirectory','libraryPath','bindingModulePath']){
             if(runtime[field]===undefined)continue;
             bundled[field]=path.posix.join(relative,path.relative(runtime.root,runtime[field]).split(path.sep).join('/'));

package/src/local-ai/whisper/build.mjs

@@ -0,0 +1,48 @@
+import path from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {mkdir} from 'node:fs/promises';
+import Is from 'strong-type';
+import {runProcess} from '../../process.mjs';
+
+const is = new Is(false);
+
+/** Build only the persistent first-party helper against an installed runtime. */
+export async function buildWhisperHelper({
+    runtime,
+    outputRoot,
+    cmake = 'cmake',
+    generator,
+    cmakeArgs = [],
+    env,
+    signal,
+    onEvent
+} = {}) {
+    if (!is.string(runtime?.directory) || !is.string(runtime?.sourceDirectory) || !is.string(outputRoot)) {
+        throw new TypeError('The selected Whisper runtime directory, matching sourceDirectory, and helper outputRoot are required.');
+    }
+    const root = path.resolve(outputRoot);
+    const build = path.join(root, 'build');
+    const source = fileURLToPath(new URL('./native/', import.meta.url));
+    await mkdir(root, {recursive: true});
+    const options = {env, signal, onEvent};
+    const configure = await runProcess(cmake, [
+        '-S', source,
+        '-B', build,
+        ...(generator ? ['-G', generator] : []),
+        `-DWHISPER_SOURCE_DIRECTORY=${path.resolve(runtime.sourceDirectory)}`,
+        `-DWHISPER_RUNTIME_DIRECTORY=${path.resolve(runtime.directory)}`,
+        `-DCMAKE_INSTALL_PREFIX=${root}`,
+        '-DCMAKE_BUILD_TYPE=Release',
+        ...cmakeArgs
+    ], options);
+    const compile = await runProcess(cmake, ['--build', build, '--config', 'Release'], options);
+    const install = await runProcess(cmake, ['--install', build, '--config', 'Release'], options);
+    return {
+        platform: process.platform,
+        architecture: process.arch,
+        root,
+        executable: path.join(root, 'bin', process.platform === 'win32' ? 'arcane-whisper.exe' : 'arcane-whisper'),
+        runtimeDirectory: path.resolve(runtime.directory),
+        diagnostics: {configure, compile, install}
+    };
+}

package/src/local-ai/whisper/config.mjs

@@ -0,0 +1,61 @@
+import Is from 'strong-type';
+import path from 'node:path';
+import {ArcaneError, ERROR_CODES} from '../../errors.mjs';
+
+const is = new Is(false);
+
+export const WHISPER_SMALL_MODEL = {
+    id: 'whisper-small',
+    url: 'https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-small.bin',
+    filename: 'ggml-small.bin'
+};
+
+/** Describe a selected native runtime and models without acquiring them. */
+export function normalizeWhisperRuntimeRequirement(record) {
+    if (record.helperRoot !== undefined && (!is.string(record.helperRoot) || !record.helperRoot)) {
+        throw new ArcaneError(ERROR_CODES.usage, 'Whisper helperRoot must name the complete selected helper directory.');
+    }
+    const helperRoot = record.helperRoot ?? (is.string(record.helperExecutable) ? path.dirname(record.helperExecutable) : undefined);
+    const backend = record.backend ?? 'auto';
+    if (!['auto', 'cuda', 'metal', 'cpu'].includes(backend)) {
+        throw new ArcaneError(ERROR_CODES.usage, `Unknown whisper.cpp backend: ${String(backend)}.`);
+    }
+    if (record.models !== undefined && !is.array(record.models)) {
+        throw new ArcaneError(ERROR_CODES.usage, 'whisper.cpp models must be an array of selected model IDs or descriptors.');
+    }
+    const models = (record.models ?? []).map(function selectedWhisperModel(value) {
+        const model = value === 'whisper-small' ? WHISPER_SMALL_MODEL : value;
+        if (!model || !is.object(model) || is.array(model) || !is.string(model.id) || !model.id) {
+            throw new ArcaneError(ERROR_CODES.usage, 'A Whisper model needs a descriptor with an id, or the built-in whisper-small model ID.');
+        }
+        if ((!is.string(model.path) || !model.path) && (!is.string(model.url) || !model.url)) {
+            throw new ArcaneError(ERROR_CODES.usage, `Whisper model ${model.id} needs its selected path or URL.`);
+        }
+        return {...model};
+    });
+    if (record.variants !== undefined && (!is.array(record.variants) || record.variants.length === 0)) {
+        throw new ArcaneError(ERROR_CODES.usage, 'whisper.cpp variants must be a nonempty array when supplied.');
+    }
+    const variants = record.variants?.map(function selectedWhisperVariant(variant) {
+        if (!variant || !is.object(variant) || is.array(variant) || !['cuda', 'metal', 'cpu'].includes(variant.backend)) {
+            throw new ArcaneError(ERROR_CODES.usage, 'Each Whisper runtime variant needs its cuda, metal, or cpu backend.');
+        }
+        if ((!is.string(variant.root) || !variant.root) && (!is.string(variant.url) || !variant.url)) {
+            throw new ArcaneError(ERROR_CODES.usage, `Whisper ${variant.backend} needs its complete runtime root or archive URL.`);
+        }
+        return {...variant};
+    });
+    if (record.modelId !== undefined && (!is.string(record.modelId) || !models.some(function matchingModel(model) {
+        return model.id === record.modelId;
+    }))) {
+        throw new ArcaneError(ERROR_CODES.usage, 'Whisper modelId must name one of the explicitly selected models.');
+    }
+    return {
+        ...record,
+        version: record.version ?? '1.9.4',
+        backend,
+        models,
+        ...(helperRoot === undefined ? {} : {helperRoot}),
+        ...(variants ? {variants} : {})
+    };
+}