@qvac/sdk 0.18.1 → 0.19.0

package/dist/src/client/config-loader/resolve-config.node.js

@@ -0,0 +1,198 @@
+/**
+ * Config loader for Node.js runtime
+ * Uses Node.js fs/promises and path modules
+ */
+import { promises as fs } from 'fs';
+import path from 'path';
+import { pathToFileURL } from 'url';
+import { validateConfig, parseJsonConfig } from './config-utils.js';
+import { ConfigFileInvalidError, ConfigFileParseFailedError } from '../../utils/errors-client.js';
+import { getClientLogger } from '../../logging/index.js';
+const logger = getClientLogger();
+/** Config filenames searched under a project root (bundle/verify/commands). */
+export const CONFIG_CANDIDATES = [
+    'qvac.config.ts',
+    'qvac.config.mjs',
+    'qvac.config.js',
+    'qvac.config.json'
+];
+async function findProjectRoot() {
+    try {
+        let currentDir = path.resolve(process.cwd());
+        const root = path.parse(currentDir).root;
+        while (currentDir !== root) {
+            try {
+                const packageJsonPath = path.join(currentDir, 'package.json');
+                await fs.access(packageJsonPath);
+                return currentDir;
+            }
+            catch {
+                const parentDir = path.dirname(currentDir);
+                if (parentDir === currentDir) {
+                    break;
+                }
+                currentDir = parentDir;
+            }
+        }
+    }
+    catch (error) {
+        logger.debug('Project root search failed, using cwd:', { error });
+    }
+    return process.cwd();
+}
+async function fileExists(filePath) {
+    try {
+        await fs.access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function readFile(filePath) {
+    return await fs.readFile(filePath, { encoding: 'utf-8' });
+}
+async function loadJsonConfig(filePath) {
+    const content = await readFile(filePath);
+    const parsed = parseJsonConfig(content, filePath);
+    return validateConfig(parsed);
+}
+async function loadJsConfig(filePath) {
+    try {
+        let importPath = filePath;
+        // Windows requires file:// URLs for dynamic imports
+        if (process.platform === 'win32' && !process.env['JEST_WORKER_ID']) {
+            importPath = pathToFileURL(filePath).toString();
+        }
+        const configModule = await import(importPath);
+        return validateConfig(configModule.default || configModule);
+    }
+    catch (error) {
+        throw new ConfigFileParseFailedError(filePath, error instanceof Error ? error.message : String(error), error);
+    }
+}
+async function loadTsConfig(filePath) {
+    let tsxApiPath;
+    try {
+        const { createRequire } = await import('node:module');
+        const require = createRequire(import.meta.url);
+        tsxApiPath = require.resolve('tsx/esm/api');
+    }
+    catch (error) {
+        throw new ConfigFileInvalidError(filePath, 'Loading a TypeScript qvac.config.ts requires the optional peer dependency `tsx`. Install it as a devDependency, or use qvac.config.mjs / qvac.config.js / qvac.config.json instead.', error);
+    }
+    try {
+        const tsxModule = (await import(tsxApiPath));
+        const mod = await tsxModule.tsImport(filePath, import.meta.url);
+        return validateConfig(mod.default ?? mod);
+    }
+    catch (error) {
+        throw new ConfigFileParseFailedError(filePath, error instanceof Error ? error.message : String(error), error);
+    }
+}
+/** Load and validate a config file at an explicit path (used by RPC init and commands). */
+export async function loadConfigFromPath(configPath) {
+    const ext = path.extname(configPath).toLowerCase();
+    if (ext === '.json') {
+        return loadJsonConfig(configPath);
+    }
+    if (ext === '.js' || ext === '.mjs') {
+        return loadJsConfig(configPath);
+    }
+    if (ext === '.ts') {
+        return loadTsConfig(configPath);
+    }
+    throw new ConfigFileInvalidError(configPath, `Unsupported config format: ${ext}. Use .json, .js, .mjs, or .ts`);
+}
+async function findConfigFileInDir(searchDir) {
+    for (const name of CONFIG_CANDIDATES) {
+        const filePath = path.resolve(searchDir, name);
+        if (await fileExists(filePath)) {
+            return filePath;
+        }
+    }
+    return undefined;
+}
+/**
+ * Resolve a config file path under `projectRoot` (or an explicit relative/absolute path).
+ * Used by `bundleSdk` / `verifyBundle` when the caller supplies `projectRoot`.
+ */
+export async function resolveConfigFileInProject(projectRoot, explicitPath) {
+    if (explicitPath) {
+        const absPath = path.isAbsolute(explicitPath)
+            ? explicitPath
+            : path.join(projectRoot, explicitPath);
+        if (await fileExists(absPath)) {
+            return absPath;
+        }
+        throw new ConfigFileInvalidError(absPath, 'Config file not found at explicit path');
+    }
+    const found = await findConfigFileInDir(projectRoot);
+    return found ?? null;
+}
+/**
+ * Load `qvac.config.*` for a known project directory (commands tooling API).
+ */
+export async function resolveConfigForProject(projectRoot, explicitPath) {
+    const configPath = await resolveConfigFileInProject(projectRoot, explicitPath);
+    if (!configPath) {
+        return { configPath: null, config: {} };
+    }
+    const config = await loadConfigFromPath(configPath);
+    return { configPath, config };
+}
+function getResourcesPath() {
+    const { resourcesPath } = process;
+    return typeof resourcesPath === 'string' ? resourcesPath : undefined;
+}
+async function findPackagedConfig() {
+    const resourcesPath = getResourcesPath();
+    if (!resourcesPath)
+        return undefined;
+    const candidates = [
+        path.join(resourcesPath, 'app', 'qvac.config.json'),
+        path.join(resourcesPath, 'app.asar.unpacked', 'qvac.config.json'),
+        path.join(resourcesPath, 'qvac.config.json')
+    ];
+    for (const candidate of candidates) {
+        if (await fileExists(candidate)) {
+            return candidate;
+        }
+    }
+    return undefined;
+}
+/**
+ * Resolution order for Node.js:
+ * 1. QVAC_CONFIG_PATH environment variable
+ * 2. Packaged Electron app (via process.resourcesPath)
+ * 3. Config file in project root (qvac.config.ts, qvac.config.js, qvac.config.json)
+ * 4. SDK defaults
+ */
+export async function resolveConfig() {
+    const configPath = process.env['QVAC_CONFIG_PATH'];
+    if (configPath) {
+        const normalizedPath = path.resolve(configPath);
+        if (await fileExists(normalizedPath)) {
+            const config = await loadConfigFromPath(normalizedPath);
+            logger.info(`✅ Loaded config from: ${normalizedPath}`);
+            return config;
+        }
+    }
+    const packagedConfig = await findPackagedConfig();
+    if (packagedConfig) {
+        const config = await loadJsonConfig(packagedConfig);
+        logger.info(`✅ Loaded config from packaged app: ${packagedConfig}`);
+        return config;
+    }
+    const projectRoot = await findProjectRoot();
+    if (projectRoot) {
+        const configFilePath = await findConfigFileInDir(projectRoot);
+        if (configFilePath) {
+            const config = await loadConfigFromPath(configFilePath);
+            logger.info(`✅ Loaded config from: ${configFilePath}`);
+            return config;
+        }
+    }
+    logger.info('ℹ️ No config file found, using SDK defaults');
+    return undefined;
+}

package/dist/src/client/init-hooks.d.ts

@@ -0,0 +1,21 @@
+import type { QvacConfig, RuntimeContext } from '@qvac/inference/surface';
+type ResolveConfigFn = () => Promise<QvacConfig | undefined>;
+interface RPCClient {
+    request(command: number): any;
+}
+/**
+ * Initializes SDK configuration and runtime context.
+ * Config is loaded once and becomes immutable on the worker side.
+ *
+ * @param rpc - The RPC client instance
+ * @param resolveConfig - Runtime-specific config resolver function
+ * @param runtimeContext - Optional runtime context (platform, device info)
+ */
+export declare function initializeConfig(rpc: RPCClient, resolveConfig: ResolveConfigFn, runtimeContext?: RuntimeContext): Promise<void>;
+/**
+ * Legacy function for backward compatibility
+ * @deprecated Use initializeConfig instead
+ */
+export declare function replayConfigIfCached(): void;
+export {};
+//# sourceMappingURL=init-hooks.d.ts.map

package/dist/src/client/init-hooks.js

@@ -0,0 +1,62 @@
+import { getClientLogger, setGlobalLogLevel, setGlobalConsoleOutput } from '../logging/index.js';
+import { SetConfigFailedError } from '../utils/errors-client.js';
+const logger = getClientLogger();
+function applyClientLoggerSettings(config) {
+    if (config.loggerLevel !== undefined) {
+        setGlobalLogLevel(config.loggerLevel);
+    }
+    if (config.loggerConsoleOutput !== undefined) {
+        setGlobalConsoleOutput(config.loggerConsoleOutput);
+    }
+}
+async function sendInitMessage(rpc, config, runtimeContext) {
+    const initMessage = {
+        type: '__init_config',
+        config,
+        runtimeContext
+    };
+    const req = rpc.request(1);
+    req.send(JSON.stringify(initMessage), 'utf8');
+    const response = await req.reply('utf8');
+    const parsed = JSON.parse(response.toString());
+    if (!parsed.success) {
+        throw new SetConfigFailedError(parsed.error ?? 'Unknown error');
+    }
+}
+/**
+ * Initializes SDK configuration and runtime context.
+ * Config is loaded once and becomes immutable on the worker side.
+ *
+ * @param rpc - The RPC client instance
+ * @param resolveConfig - Runtime-specific config resolver function
+ * @param runtimeContext - Optional runtime context (platform, device info)
+ */
+export async function initializeConfig(rpc, resolveConfig, runtimeContext) {
+    const config = await resolveConfig();
+    // Nothing to initialize
+    if (!config && !runtimeContext) {
+        return;
+    }
+    // Apply client-side logger settings
+    if (config) {
+        applyClientLoggerSettings(config);
+        logger.info('📦 Initializing SDK config');
+    }
+    if (runtimeContext) {
+        logger.info('📱 Runtime context:', runtimeContext);
+    }
+    try {
+        await sendInitMessage(rpc, config, runtimeContext);
+        logger.info('✅ Initialization complete');
+    }
+    catch (error) {
+        logger.error('❌ Initialization failed:', error);
+    }
+}
+/**
+ * Legacy function for backward compatibility
+ * @deprecated Use initializeConfig instead
+ */
+export function replayConfigIfCached() {
+    logger.warn('⚠️ replayConfigIfCached is deprecated and has no effect. Config is now loaded from file during initialization.');
+}

package/dist/src/client/plugins-factory.d.ts

@@ -0,0 +1,7 @@
+import * as hostApi from './api/index.js';
+import type { QvacPlugin } from '@qvac/inference/surface';
+/**
+ * Register plugins and return the client host API.
+ */
+export declare function plugins(pluginList: readonly QvacPlugin[]): typeof hostApi;
+//# sourceMappingURL=plugins-factory.d.ts.map

package/dist/src/client/plugins-factory.js

@@ -0,0 +1,9 @@
+import { registerPlugins } from '../server/plugins/index.js';
+import * as hostApi from './api/index.js';
+/**
+ * Register plugins and return the client host API.
+ */
+export function plugins(pluginList) {
+    registerPlugins(pluginList);
+    return hostApi;
+}

package/dist/src/client/rpc/bare-client.d.ts

@@ -0,0 +1,6 @@
+export declare function getRPC(): void;
+export declare function createDuplexSession(): void;
+export declare function close(): void;
+export declare function getWorkerLifeSignal(): null;
+export declare function notifyChannelClosed(): void;
+//# sourceMappingURL=bare-client.d.ts.map

package/dist/src/client/rpc/bare-client.js

@@ -0,0 +1,21 @@
+// Bare-safe stub for the `#rpc` client transport. The SDK's RPC client is a
+// Node/Electron/Expo concern; on Bare you use @qvac/inference directly, so the Bare
+// worker bundle never invokes it. This exists only so bare-pack can resolve
+// `#rpc` under the `bare` condition to a target free of `node:` builtins.
+// TODO: revisit for a cleaner way to keep the client transport out of the worker bundle.
+function notAvailable() {
+    throw new Error('@qvac/sdk RPC client is not available on Bare; use @qvac/inference directly.');
+}
+export function getRPC() {
+    return notAvailable();
+}
+export function createDuplexSession() {
+    return notAvailable();
+}
+export function close() {
+    return notAvailable();
+}
+export function getWorkerLifeSignal() {
+    return null;
+}
+export function notifyChannelClosed() { }

package/dist/src/client/rpc/expo-rpc-client.js

@@ -0,0 +1,195 @@
+import RPC from 'bare-rpc';
+import { RPCConnectionFailedError } from '../../utils/errors-client.js';
+import { initializeConfig } from '../init-hooks.js';
+import { resolveConfig } from '../config-loader/resolve-config.expo.js';
+import { getClientLogger } from '../../logging/index.js';
+import { getDeviceInfo } from './expo-device-info.js';
+const logger = getClientLogger();
+let rpcInstance = null;
+let rpcPromise = null;
+let workletInstance = null;
+let workletInitialized = false;
+let cachedRuntimeContext;
+// Set while close() is in flight. Concurrent callers share the same
+// promise instead of double-sending __shutdown__ or re-entering the
+// terminate block on already-null state.
+let closingPromise = null;
+logger.debug('EXPO RPC Client bundle');
+async function getRuntimeContext() {
+    if (cachedRuntimeContext) {
+        return cachedRuntimeContext;
+    }
+    const { platform, deviceModel, deviceBrand } = await getDeviceInfo();
+    cachedRuntimeContext = {
+        runtime: 'react-native',
+        platform,
+        deviceModel,
+        deviceBrand
+    };
+    return cachedRuntimeContext;
+}
+// No child-process exit on Expo (Worklet lifecycle) — `#rpc` interface stub.
+export function getWorkerLifeSignal() {
+    return null;
+}
+// No life signal on Expo, so the RPC layer never calls this — `#rpc` interface stub.
+export function notifyChannelClosed() { }
+export async function getRPC() {
+    if (rpcInstance) {
+        return rpcInstance;
+    }
+    if (rpcPromise) {
+        return rpcPromise;
+    }
+    rpcPromise = (async () => {
+        if (workletInstance) {
+            logger.debug('🔄 Reusing existing worklet');
+            rpcInstance = new RPC(workletInstance.IPC, () => { });
+            // Only initialize once per worklet - server state persists
+            if (!workletInitialized) {
+                const runtimeContext = await getRuntimeContext();
+                await initializeConfig(rpcInstance, resolveConfig, runtimeContext);
+                workletInitialized = true;
+            }
+            return rpcInstance;
+        }
+        const { Paths } = await import('expo-file-system');
+        const bareKitModule = await import('react-native-bare-kit');
+        const worklet = new bareKitModule.Worklet();
+        workletInstance = worklet;
+        logger.debug('Starting new worklet');
+        // Load the mobile bundle - generated by expo plugin during prebuild
+        // The expo plugin handles bundle selection:
+        // 1. Uses qvac/worker.bundle.js if exists (user pre-generated)
+        // 2. Generates tree-shaken bundle if qvac.config.* exists
+        // 3. Generates default bundle (all plugins) otherwise
+        let mobileBundle;
+        try {
+            mobileBundle = require('@qvac/sdk/worker.mobile.bundle');
+        }
+        catch (error) {
+            const message = 'Failed to load mobile worker bundle. Make sure the QVAC Expo plugin is configured. ' +
+                `Add '@qvac/sdk/expo-plugin' to your app.json plugins array. ` +
+                `Error: ${String(error)}`;
+            logger.error(message);
+            throw new RPCConnectionFailedError(message, error instanceof Error ? error : undefined);
+        }
+        worklet.start('worker.bundle', mobileBundle, [
+            // Normalize arg number across platforms
+            'react-native-bare-kit',
+            'worker.js',
+            JSON.stringify({
+                HOME_DIR: Paths.document.uri.replace('file://', '')
+            })
+        ]);
+        logger.info('Worklet started');
+        rpcInstance = new RPC(worklet.IPC, () => {
+            // Use this for async callbacks
+        });
+        const runtimeContext = await getRuntimeContext();
+        await initializeConfig(rpcInstance, resolveConfig, runtimeContext);
+        workletInitialized = true;
+        return rpcInstance;
+    })();
+    try {
+        return await rpcPromise;
+    }
+    catch (error) {
+        logger.error(`Failed to initialize RPC: ${String(error)}`);
+        throw error;
+    }
+    finally {
+        rpcPromise = null;
+    }
+}
+const SHUTDOWN_RPC_TIMEOUT_MS = 10_000;
+/**
+ * Pre-terminate cleanup roundtrip. Sends an internal `__shutdown__` message
+ * to the worker so it can clear addon plugin registries (calls each addon's
+ * `releaseLogger` → frees env-bound js_ref_t state) and unload all model
+ * instances BEFORE we kill the worklet.
+ *
+ * Without this, the worklet's V8 isolate dies while addon static state still
+ * holds js_ref_t handles into it; the next worklet's first `setLogger` call
+ * trips a V8 GlobalHandle assertion (brk 0 / SIGTRAP) and the iOS app dies.
+ *
+ * Best-effort: never throws. Falls through to terminate even on timeout.
+ */
+async function sendShutdownMessage(rpc) {
+    let timer;
+    try {
+        await Promise.race([
+            (async () => {
+                const req = rpc.request(1);
+                req.send(JSON.stringify({ type: '__shutdown__' }), 'utf8');
+                const response = await req.reply('utf8');
+                const parsed = JSON.parse(String(response));
+                if (!parsed.success) {
+                    throw new Error(parsed.error ?? 'Worker reported cleanup failure');
+                }
+            })(),
+            new Promise((_, reject) => {
+                timer = setTimeout(() => reject(new Error(`Worker did not ack __shutdown__ within ${SHUTDOWN_RPC_TIMEOUT_MS}ms`)), SHUTDOWN_RPC_TIMEOUT_MS);
+            })
+        ]);
+    }
+    catch (error) {
+        // Best-effort: log but don't block termination if cleanup fails.
+        logger.warn(`⚠️ Pre-terminate worker cleanup failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+export async function close() {
+    // Concurrent callers (or a getRPC retry that overlaps with a manual
+    // close) share the in-flight close promise instead of each sending
+    // their own __shutdown__ and racing on the terminate block.
+    if (closingPromise)
+        return closingPromise;
+    closingPromise = (async () => {
+        logger.info('🧹 Closing RPC client (Expo)');
+        // The inference addons self-pin (RTLD_NODELETE, qvac-lib-inference-addon-cpp
+        // >= 1.2.2), so dlclose() during terminate() no longer unmaps addon code
+        // with dangling pthread_key_t destructors. terminate() is therefore safe on
+        // every platform (previously it was skipped on non-iOS to avoid a SIGSEGV in
+        // pthread_key_clean_all), so we always run the full pre-terminate cleanup +
+        // terminate path.
+        if (rpcInstance) {
+            logger.info('🧹 Requesting worker pre-terminate cleanup');
+            await sendShutdownMessage(rpcInstance);
+        }
+        rpcInstance = null;
+        rpcPromise = null;
+        if (workletInstance) {
+            logger.info('🐻🔫 Terminating bare worklet');
+            try {
+                workletInstance.terminate();
+            }
+            catch (error) {
+                logger.debug('Failed to terminate worklet', { error });
+            }
+            workletInstance = null;
+            workletInitialized = false;
+        }
+    })();
+    try {
+        await closingPromise;
+    }
+    finally {
+        // Reset so a subsequent close() (e.g. after a fresh getRPC spawned
+        // a new worklet) can run again. Body guards on rpcInstance / workletInstance
+        // make a redundant call a no-op if state is already cleared.
+        closingPromise = null;
+    }
+}
+export async function createDuplexSession(payload, commandId) {
+    const rpc = await getRPC();
+    const req = rpc.request(commandId);
+    const requestStream = req.createRequestStream();
+    const responseStream = req.createResponseStream({ encoding: 'utf-8' });
+    // Pre-encode payload — RN/Hermes lacks a global `Buffer`, so `write(string, "utf-8")` would throw.
+    requestStream.write(new TextEncoder().encode(payload));
+    return { requestStream, responseStream };
+}

package/dist/src/client/rpc/init-timeout.d.ts

@@ -0,0 +1,26 @@
+/** Fallback when neither the environment nor `qvac.config.*` sets a value. */
+export declare const DEFAULT_RPC_INIT_TIMEOUT_MS = 30000;
+/**
+ * Overrides `rpcInitTimeoutMs` from the config file. Read before the worker is
+ * spawned, so it is the only knob available to hosts that cannot ship a config
+ * file (packaged apps, CI images, one-off debugging runs).
+ */
+export declare const RPC_INIT_TIMEOUT_ENV_VAR = "QVAC_RPC_INIT_TIMEOUT_MS";
+interface ResolveRPCInitTimeoutOptions {
+    envValue?: string | undefined;
+    /** Already checked against `z.number().int().positive()` by config validation. */
+    configValue?: number | undefined;
+    /** Invoked for a rejected environment value, so this module needs no logger. */
+    onInvalidEnvValue?: (envValue: string) => void;
+}
+/**
+ * Resolve the worker handshake timeout: environment variable, then config file,
+ * then the built-in default.
+ *
+ * Only the environment is checked, being free text that reaches here
+ * unvalidated. It is reported and skipped rather than thrown, because a
+ * mistyped tuning value must not become a hard SDK initialization failure.
+ */
+export declare function resolveRPCInitTimeoutMs({ envValue, configValue, onInvalidEnvValue }?: ResolveRPCInitTimeoutOptions): number;
+export {};
+//# sourceMappingURL=init-timeout.d.ts.map

package/dist/src/client/rpc/init-timeout.js

@@ -0,0 +1,25 @@
+/** Fallback when neither the environment nor `qvac.config.*` sets a value. */
+export const DEFAULT_RPC_INIT_TIMEOUT_MS = 30_000;
+/**
+ * Overrides `rpcInitTimeoutMs` from the config file. Read before the worker is
+ * spawned, so it is the only knob available to hosts that cannot ship a config
+ * file (packaged apps, CI images, one-off debugging runs).
+ */
+export const RPC_INIT_TIMEOUT_ENV_VAR = 'QVAC_RPC_INIT_TIMEOUT_MS';
+/**
+ * Resolve the worker handshake timeout: environment variable, then config file,
+ * then the built-in default.
+ *
+ * Only the environment is checked, being free text that reaches here
+ * unvalidated. It is reported and skipped rather than thrown, because a
+ * mistyped tuning value must not become a hard SDK initialization failure.
+ */
+export function resolveRPCInitTimeoutMs({ envValue, configValue, onInvalidEnvValue } = {}) {
+    if (envValue !== undefined && envValue.trim() !== '') {
+        const parsed = Number(envValue);
+        if (Number.isInteger(parsed) && parsed > 0)
+            return parsed;
+        onInvalidEnvValue?.(envValue);
+    }
+    return configValue ?? DEFAULT_RPC_INIT_TIMEOUT_MS;
+}