@qvac/sdk 0.8.0 → 1.0.0

package/dist/pear/pre.d.ts

@@ -1,18 +0,0 @@
-/**
- * QVAC Pear Pre-Hook
- *
- * Invoked by Pear before `pear run` or `pear stage` to:
- * 1. Generate `qvac/worker.pear.entry.mjs` with selected plugins
- * 2. Persist `pear.stage.entrypoints` to package.json for routing
- *
- * @example package.json configuration
- * ```json
- * {
- *   "pear": {
- *     "pre": ["@qvac/sdk/pear-pre"]
- *   }
- * }
- * ```
- */
-export {};
-//# sourceMappingURL=pre.d.ts.map

package/dist/pear/pre.js

@@ -1,433 +0,0 @@
-/**
- * QVAC Pear Pre-Hook
- *
- * Invoked by Pear before `pear run` or `pear stage` to:
- * 1. Generate `qvac/worker.pear.entry.mjs` with selected plugins
- * 2. Persist `pear.stage.entrypoints` to package.json for routing
- *
- * @example package.json configuration
- * ```json
- * {
- *   "pear": {
- *     "pre": ["@qvac/sdk/pear-pre"]
- *   }
- * }
- * ```
- */
-import * as cenc from "compact-encoding";
-import pearPipe from "pear-pipe";
-import fs from "bare-fs";
-import path from "bare-path";
-const CONFIG_CANDIDATES = [
-    "qvac.config.json",
-    "qvac.config.js",
-    "qvac.config.mjs",
-    "qvac.config.ts",
-];
-const BUILTIN_PLUGINS = [
-    "@qvac/sdk/llamacpp-completion/plugin",
-    "@qvac/sdk/llamacpp-embedding/plugin",
-    "@qvac/sdk/whispercpp-transcription/plugin",
-    "@qvac/sdk/nmtcpp-translation/plugin",
-    "@qvac/sdk/onnx-tts/plugin",
-    "@qvac/sdk/onnx-ocr/plugin",
-];
-const BUILTIN_PLUGIN_EXPORTS = {
-    "llamacpp-completion": "llmPlugin",
-    "llamacpp-embedding": "embeddingsPlugin",
-    "whispercpp-transcription": "whisperPlugin",
-    "nmtcpp-translation": "nmtPlugin",
-    "onnx-tts": "ttsPlugin",
-    "onnx-ocr": "ocrPlugin",
-};
-const SDK_NAME = "@qvac/sdk";
-const DEFAULT_PEAR_WORKER = "worker.js";
-const PEAR_WORKER_ENTRY_PATH = "qvac/worker.pear.entry.mjs";
-const LOG_PREFIX = "[qvac/pear-pre]";
-/** Normalize path to Pear config format (POSIX-style, leading slash) */
-function toPearConfigPath(pathFromAppRoot) {
-    let p = String(pathFromAppRoot).replaceAll("\\", "/");
-    if (p.startsWith("./"))
-        p = p.slice(2);
-    if (!p.startsWith("/"))
-        p = `/${p}`;
-    return p.replaceAll("/./", "/").replace(/\/{2,}/g, "/");
-}
-function toPosixPath(p) {
-    return String(p).replaceAll("\\", "/");
-}
-function pathToFileUrl(absPath) {
-    let p = toPosixPath(absPath);
-    // Windows drive letter paths need a leading slash in file:// URLs.
-    if (/^[A-Za-z]:\//.test(p))
-        p = `/${p}`;
-    if (!p.startsWith("/"))
-        p = `/${p}`;
-    const segments = p.split("/");
-    const encoded = segments
-        .map((seg, idx) => {
-        if (idx === 0)
-            return "";
-        // Preserve "C:" drive segment in Windows file URLs (file:///C:/...)
-        if (idx === 1 && /^[A-Za-z]:$/.test(seg))
-            return seg;
-        return encodeURIComponent(seg);
-    })
-        .join("/");
-    return `file://${encoded}`;
-}
-function detectJsonIndent(raw) {
-    const match = raw.match(/\n([ \t]+)"/);
-    if (match?.[1])
-        return match[1];
-    return 2;
-}
-function detectJsonNewline(raw) {
-    return raw.includes("\r\n") ? "\r\n" : "\n";
-}
-function ensureObjectProp(obj, prop) {
-    const existing = obj[prop];
-    if (existing === undefined) {
-        const created = {};
-        obj[prop] = created;
-        return created;
-    }
-    if (typeof existing === "object" && existing && !Array.isArray(existing)) {
-        return existing;
-    }
-    throw new Error(`package.json "${prop}" must be an object`);
-}
-function normalizeStringArray(value) {
-    if (value === undefined || value === null)
-        return [];
-    if (typeof value === "string")
-        return value.length ? [value] : [];
-    if (Array.isArray(value))
-        return uniqStrings(value);
-    throw new Error("Expected an array of strings");
-}
-function atomicWriteFileSync(targetPath, content) {
-    const tmpPath = `${targetPath}.qvac-pre.tmp`;
-    fs.writeFileSync(tmpPath, content, "utf8");
-    fs.renameSync(tmpPath, targetPath);
-}
-function normalizePearWorkerPath(value) {
-    if (typeof value !== "string")
-        return DEFAULT_PEAR_WORKER;
-    let p = value.trim();
-    if (!p)
-        return DEFAULT_PEAR_WORKER;
-    p = toPosixPath(p);
-    if (/^[A-Za-z]:\//.test(p)) {
-        throw new Error(`"pearWorker" must be a path inside the app root (got absolute path: ${JSON.stringify(value)})`);
-    }
-    if (p.startsWith("./"))
-        p = p.slice(2);
-    while (p.startsWith("/"))
-        p = p.slice(1);
-    if (!p)
-        return DEFAULT_PEAR_WORKER;
-    if (p === "." || p === ".." || p.startsWith("../") || p.includes("/../")) {
-        throw new Error(`"pearWorker" must be a path inside the app root (got: ${JSON.stringify(value)})`);
-    }
-    return p;
-}
-/**
- * Converts an absolute path to a relative ESM import specifier, using POSIX separators.
- */
-function toRelativeImportSpecifier(fromDir, targetPath) {
-    let rel = path.relative(fromDir, targetPath);
-    rel = toPosixPath(rel);
-    if (!rel.startsWith("."))
-        rel = `./${rel}`;
-    return rel;
-}
-/** Extract unique strings from an array, preserving order */
-function uniqStrings(values) {
-    if (!Array.isArray(values))
-        return [];
-    const out = [];
-    const seen = new Set();
-    for (const v of values) {
-        if (typeof v === "string" && !seen.has(v)) {
-            seen.add(v);
-            out.push(v);
-        }
-    }
-    return out;
-}
-/** Ensure array contains required values, returning new array and change flag */
-function ensureArrayIncludes(existing, required) {
-    const next = [...existing];
-    const set = new Set(existing);
-    let changed = false;
-    for (const v of required) {
-        if (!set.has(v)) {
-            set.add(v);
-            next.push(v);
-            changed = true;
-        }
-    }
-    return { next, changed };
-}
-/**
- * Persist pear.stage.entrypoints to package.json.
- *
- * Required because workers are spawned with --no-pre, bypassing dynamic config.
- * pear-state merges stage.entrypoints into unrouted automatically.
- */
-function persistStageEntrypointsToPackageJson(appRoot, requiredEntrypoints) {
-    const packageJsonPath = path.join(appRoot, "package.json");
-    if (!fs.existsSync(packageJsonPath)) {
-        throw new Error(`package.json not found at ${packageJsonPath}`);
-    }
-    const raw = fs.readFileSync(packageJsonPath, "utf8");
-    const newline = detectJsonNewline(raw);
-    const indent = detectJsonIndent(raw);
-    const hasFinalNewline = raw.endsWith("\n") || raw.endsWith("\r\n");
-    let pkg;
-    try {
-        pkg = JSON.parse(raw);
-    }
-    catch (err) {
-        throw new Error(`Failed to parse ${packageJsonPath}: ${String(err)}`);
-    }
-    const pear = ensureObjectProp(pkg, "pear");
-    const stage = ensureObjectProp(pear, "stage");
-    const existing = normalizeStringArray(stage["entrypoints"]);
-    const required = uniqStrings(requiredEntrypoints);
-    const { next, changed } = ensureArrayIncludes(existing, required);
-    if (!changed)
-        return;
-    stage["entrypoints"] = next;
-    let nextRaw = JSON.stringify(pkg, null, indent);
-    if (newline === "\r\n")
-        nextRaw = nextRaw.replaceAll("\n", "\r\n");
-    if (hasFinalNewline)
-        nextRaw += newline;
-    atomicWriteFileSync(packageJsonPath, nextRaw);
-}
-/** Extract app root directory from Pear's applink */
-function getAppRoot() {
-    const applink = Pear.config?.applink;
-    if (typeof applink !== "string" || applink.length === 0) {
-        throw new Error("Pear.config.applink is not available");
-    }
-    // Pear provides a file:// URL to the application root.
-    let pathname;
-    let url;
-    try {
-        url = new URL(applink);
-    }
-    catch {
-        // Some environments may provide a plain filesystem path instead of a URL.
-        return path.normalize(applink);
-    }
-    if (url.protocol !== "file:") {
-        throw new Error(`Expected Pear.config.applink to be a file:// URL (got: ${applink})`);
-    }
-    pathname = url.pathname;
-    try {
-        pathname = decodeURIComponent(pathname);
-    }
-    catch {
-        // If decoding fails, keep the raw pathname.
-    }
-    // Handle Windows paths (e.g., /C:/path)
-    if (pathname[0] === "/" && pathname[2] === ":") {
-        pathname = pathname.slice(1);
-    }
-    return path.normalize(pathname);
-}
-/** Find the first existing qvac config file */
-function findConfigFile(appRoot) {
-    for (const candidate of CONFIG_CANDIDATES) {
-        const configPath = path.join(appRoot, candidate);
-        if (fs.existsSync(configPath)) {
-            return configPath;
-        }
-    }
-    return null;
-}
-/** Load and parse a qvac config file */
-async function loadConfig(configPath) {
-    const ext = path.extname(configPath).toLowerCase();
-    if (ext === ".json") {
-        const content = fs.readFileSync(configPath, "utf8");
-        try {
-            return JSON.parse(content);
-        }
-        catch (err) {
-            throw new Error(`Failed to parse ${configPath}: ${String(err)}`);
-        }
-    }
-    if (ext === ".js" || ext === ".mjs") {
-        const module = (await import(pathToFileUrl(configPath)));
-        return module.default ?? module;
-    }
-    if (ext === ".ts") {
-        throw new Error("TypeScript config not supported in Pear pre-hook. Use qvac.config.json or qvac.config.mjs.");
-    }
-    throw new Error(`Unsupported config format: ${ext}. Use .json, .js, or .mjs`);
-}
-/** Discover and load qvac config, returning null if not found */
-async function discoverConfig(appRoot) {
-    const configPath = findConfigFile(appRoot);
-    if (!configPath) {
-        return { config: null, configFile: null };
-    }
-    const config = await loadConfig(configPath);
-    return { config, configFile: path.basename(configPath) };
-}
-/** Resolve plugin set from config or default to all built-in plugins */
-function resolvePlugins(config) {
-    const fromConfig = uniqStrings(config?.plugins);
-    if (fromConfig.length)
-        return fromConfig;
-    return [...BUILTIN_PLUGINS];
-}
-/** Parse SDK builtin plugin specifier to extract export info */
-function parseBuiltinSpecifier(specifier) {
-    const prefix = `${SDK_NAME}/`;
-    const pluginSuffix = "/plugin";
-    if (specifier.startsWith(prefix) && specifier.endsWith(pluginSuffix)) {
-        const middle = specifier.slice(prefix.length, -pluginSuffix.length);
-        const exportName = BUILTIN_PLUGIN_EXPORTS[middle];
-        if (!middle.includes("/") && exportName) {
-            return { suffix: middle, exportName };
-        }
-    }
-    return null;
-}
-/** Generate the Pear worker entry file content */
-function generatePearWorkerEntry(plugins, appWorkerPath) {
-    const imports = [];
-    const registrations = [];
-    let varIndex = 0;
-    for (const specifier of plugins) {
-        const builtin = parseBuiltinSpecifier(specifier);
-        if (builtin) {
-            imports.push(`import { ${builtin.exportName} } from "${SDK_NAME}/${builtin.suffix}/plugin";`);
-            registrations.push(`registerPlugin(${builtin.exportName});`);
-        }
-        else {
-            const varName = `customPlugin${varIndex++}`;
-            imports.push(`import ${varName} from "${specifier}";`);
-            registrations.push(`registerPlugin(${varName});`);
-        }
-    }
-    const pluginsList = plugins.map((p) => `*   - ${p}`).join("\n");
-    return `/**
- * QVAC Pear Worker Entry (auto-generated)
- * Plugins: ${plugins.length}
- *
-${pluginsList}
- */
-
-import { registerPlugin } from "${SDK_NAME}/plugins";
-
-${imports.join("\n")}
-
-${registrations.join("\n")}
-
-await import(${JSON.stringify(appWorkerPath)});
-`;
-}
-/** Write worker entry file if content changed (idempotent) */
-function writeWorkerEntryIfChanged(appRoot, content) {
-    const outputDir = path.join(appRoot, "qvac");
-    const entryPath = path.join(appRoot, PEAR_WORKER_ENTRY_PATH);
-    if (fs.existsSync(entryPath)) {
-        try {
-            if (fs.readFileSync(entryPath, "utf8") === content) {
-                return false;
-            }
-        }
-        catch {
-            // Will rewrite on error
-        }
-    }
-    if (!fs.existsSync(outputDir)) {
-        fs.mkdirSync(outputDir, { recursive: true });
-    }
-    atomicWriteFileSync(entryPath, content);
-    return true;
-}
-/** Main configuration handler */
-async function configure(options) {
-    const appRoot = getAppRoot();
-    const { config: qvacConfig } = await discoverConfig(appRoot);
-    const plugins = resolvePlugins(qvacConfig);
-    const pearWorker = normalizePearWorkerPath(qvacConfig?.pearWorker);
-    // Validate worker file exists
-    const workerAbs = path.join(appRoot, pearWorker);
-    if (!fs.existsSync(workerAbs)) {
-        const hint = qvacConfig?.pearWorker
-            ? `"${String(qvacConfig.pearWorker)}" (resolved to ${workerAbs})`
-            : `"${DEFAULT_PEAR_WORKER}". Set "pearWorker" in qvac.config.json to specify your worker path.`;
-        throw new Error(`Worker file not found: ${hint}`);
-    }
-    // Generate worker entry with relative import path from qvac/ directory
-    const outputDir = path.join(appRoot, "qvac");
-    const appWorkerImport = toRelativeImportSpecifier(outputDir, workerAbs);
-    const workerEntryContent = generatePearWorkerEntry(plugins, appWorkerImport);
-    writeWorkerEntryIfChanged(appRoot, workerEntryContent);
-    // Persist entrypoint to package.json for worker routing
-    const workerEntryPath = toPearConfigPath(PEAR_WORKER_ENTRY_PATH);
-    persistStageEntrypointsToPackageJson(appRoot, [workerEntryPath]);
-    return options;
-}
-// IPC Protocol
-const pipe = pearPipe();
-if (!pipe) {
-    console.error(`${LOG_PREFIX} No IPC pipe available`);
-    process.exit(1);
-}
-pipe.autoexit = true;
-let exitCode = 0;
-pipe.on("end", () => {
-    try {
-        Pear.pipe.end();
-    }
-    finally {
-        if (exitCode !== 0)
-            process.exit(exitCode);
-    }
-});
-pipe.once("error", (err) => {
-    exitCode = exitCode || 1;
-    console.error(LOG_PREFIX, err);
-});
-pipe.once("data", (data) => {
-    void (async () => {
-        let options = null;
-        try {
-            options = cenc.decode(cenc.any, data);
-        }
-        catch (err) {
-            exitCode = 1;
-            console.error(LOG_PREFIX, err);
-            try {
-                pipe.end(cenc.encode(cenc.any, { tag: "configure", data: {} }));
-            }
-            catch {
-                pipe.destroy(err);
-            }
-            return;
-        }
-        try {
-            const config = await configure(options);
-            pipe.end(cenc.encode(cenc.any, { tag: "configure", data: config }));
-        }
-        catch (err) {
-            exitCode = 1;
-            console.error(LOG_PREFIX, err);
-            try {
-                pipe.end(cenc.encode(cenc.any, { tag: "configure", data: options }));
-            }
-            catch {
-                pipe.destroy(err);
-            }
-        }
-    })();
-});

package/dist/profiling/aggregator.d.ts

@@ -1,15 +0,0 @@
-/**
- * Accumulates profiling statistics and maintains a bounded buffer of recent events.
- * Uses a ring buffer for O(1) event insertion.
- */
-import type { ProfilingEvent, AggregatedStats } from "./types";
-export declare function createAggregator(maxRecentEvents?: number): void;
-export declare function recordEvent(event: ProfilingEvent, storeInBuffer?: boolean): void;
-export declare function getAggregates(): Record<string, AggregatedStats>;
-/** Returns events in chronological order (oldest first). */
-export declare function getRecentEvents(): ProfilingEvent[];
-export declare function getEventCount(): number;
-export declare function getDroppedCount(): number;
-export declare function clearAggregator(): void;
-export declare function setMaxRecentEvents(max: number): void;
-//# sourceMappingURL=aggregator.d.ts.map

package/dist/profiling/aggregator.js

@@ -1,100 +0,0 @@
-/**
- * Accumulates profiling statistics and maintains a bounded buffer of recent events.
- * Uses a ring buffer for O(1) event insertion.
- */
-import { getGlobalSingleton } from "../utils/global-singleton.js";
-import { createRingBuffer, ringBufferPush, ringBufferToArray, ringBufferClear, ringBufferResize, ringBufferDroppedCount, } from "./ring-buffer.js";
-const DEFAULT_MAX_RECENT_EVENTS = 1000;
-const AGGREGATOR_STATE_KEY = Symbol.for("@qvac/sdk:profiler-aggregator-state");
-function getAggregatorState() {
-    return getGlobalSingleton(AGGREGATOR_STATE_KEY, () => {
-        return {
-            stats: new Map(),
-            eventBuffer: createRingBuffer(DEFAULT_MAX_RECENT_EVENTS),
-        };
-    });
-}
-export function createAggregator(maxRecentEvents = DEFAULT_MAX_RECENT_EVENTS) {
-    const state = getAggregatorState();
-    state.stats = new Map();
-    state.eventBuffer = createRingBuffer(maxRecentEvents);
-}
-function recordStats(key, value) {
-    const aggregator = getAggregatorState();
-    let statsState = aggregator.stats.get(key);
-    if (!statsState) {
-        statsState = {
-            count: 0,
-            min: Infinity,
-            max: -Infinity,
-            sum: 0,
-            last: 0,
-        };
-        aggregator.stats.set(key, statsState);
-    }
-    statsState.count++;
-    statsState.sum += value;
-    statsState.last = value;
-    if (value < statsState.min)
-        statsState.min = value;
-    if (value > statsState.max)
-        statsState.max = value;
-}
-function getStats(state) {
-    return {
-        count: state.count,
-        min: state.count > 0 ? state.min : 0,
-        max: state.count > 0 ? state.max : 0,
-        avg: state.count > 0 ? state.sum / state.count : 0,
-        sum: state.sum,
-        last: state.last,
-    };
-}
-export function recordEvent(event, storeInBuffer = true) {
-    const state = getAggregatorState();
-    if (storeInBuffer) {
-        ringBufferPush(state.eventBuffer, event);
-    }
-    if (event.ms !== undefined) {
-        const key = event.phase ? `${event.op}.${event.phase}` : event.op;
-        recordStats(key, event.ms);
-    }
-    if (event.gauges) {
-        const baseKey = event.phase ? `${event.op}.${event.phase}` : event.op;
-        for (const [gaugeName, value] of Object.entries(event.gauges)) {
-            recordStats(`${baseKey}.${gaugeName}`, value);
-        }
-    }
-}
-export function getAggregates() {
-    const state = getAggregatorState();
-    const result = {};
-    for (const [key, statsState] of state.stats) {
-        result[key] = getStats(statsState);
-    }
-    return result;
-}
-/** Returns events in chronological order (oldest first). */
-export function getRecentEvents() {
-    return ringBufferToArray(getAggregatorState().eventBuffer);
-}
-export function getEventCount() {
-    const state = getAggregatorState();
-    let total = 0;
-    for (const statsState of state.stats.values()) {
-        total += statsState.count;
-    }
-    return total;
-}
-export function getDroppedCount() {
-    return ringBufferDroppedCount(getAggregatorState().eventBuffer);
-}
-export function clearAggregator() {
-    const state = getAggregatorState();
-    state.stats.clear();
-    ringBufferClear(state.eventBuffer);
-}
-export function setMaxRecentEvents(max) {
-    const state = getAggregatorState();
-    state.eventBuffer = ringBufferResize(state.eventBuffer, max);
-}

package/dist/profiling/clock.d.ts

@@ -1,12 +0,0 @@
-/**
- * Runtime-safe monotonic clock for profiling.
- * Priority: performance.now > process.hrtime > Date.now
- */
-export type ClockSource = "performance" | "hrtime" | "date";
-export declare function getClockSource(): ClockSource;
-export declare function isMonotonic(): boolean;
-export declare function nowMs(): number;
-export declare function measureAsync<T>(fn: () => Promise<T>): Promise<[T, number]>;
-export declare function measureSync<T>(fn: () => T): [T, number];
-export declare function generateProfileId(): string;
-//# sourceMappingURL=clock.d.ts.map

package/dist/profiling/clock.js

@@ -1,51 +0,0 @@
-/**
- * Runtime-safe monotonic clock for profiling.
- * Priority: performance.now > process.hrtime > Date.now
- */
-let clockSource;
-let nowMsImpl;
-// Detect and cache the best available clock source at module load
-if (typeof globalThis !== "undefined" &&
-    typeof globalThis.performance !== "undefined" &&
-    typeof globalThis.performance.now === "function") {
-    clockSource = "performance";
-    const perfNow = globalThis.performance.now.bind(globalThis.performance);
-    nowMsImpl = () => perfNow();
-}
-else if (typeof process !== "undefined" &&
-    typeof process.hrtime === "function" &&
-    typeof process.hrtime.bigint === "function") {
-    clockSource = "hrtime";
-    const hrtime = process.hrtime.bigint.bind(process.hrtime);
-    const startNs = hrtime();
-    nowMsImpl = () => Number(hrtime() - startNs) / 1_000_000;
-}
-else {
-    clockSource = "date";
-    const startMs = Date.now();
-    nowMsImpl = () => Date.now() - startMs;
-}
-export function getClockSource() {
-    return clockSource;
-}
-export function isMonotonic() {
-    return clockSource === "performance" || clockSource === "hrtime";
-}
-export function nowMs() {
-    return nowMsImpl();
-}
-export async function measureAsync(fn) {
-    const start = nowMs();
-    const result = await fn();
-    return [result, nowMs() - start];
-}
-export function measureSync(fn) {
-    const start = nowMs();
-    const result = fn();
-    return [result, nowMs() - start];
-}
-export function generateProfileId() {
-    const timestamp = Date.now().toString(36);
-    const random = Math.random().toString(36).substring(2, 8);
-    return `${timestamp}-${random}`;
-}

package/dist/profiling/controller.d.ts

@@ -1,33 +0,0 @@
-/**
- * Central state management for profiling enablement, configuration, and recording.
- *
- * Precedence (highest to lowest):
- * 1. Per-call override
- * 2. Runtime API (enable/disable)
- * 3. Disabled default
- */
-import type { ProfilerMode, PerCallProfiling } from "../schemas/index";
-import type { ProfilerRuntimeOptions, ProfilingEvent, AggregatedStats } from "./types";
-export interface ResolvedProfilerConfig {
-    enabled: boolean;
-    mode: ProfilerMode;
-    includeServerBreakdown: boolean;
-    operationFilters: string[];
-    maxRecentEvents: number;
-}
-type RecordCallback = (event: ProfilingEvent) => void;
-export declare function enable(options?: ProfilerRuntimeOptions): void;
-export declare function disable(): void;
-export declare function isEnabled(): boolean;
-export declare function getEffectiveConfig(): ResolvedProfilerConfig;
-export declare function shouldProfile(operation: string, perCallOptions?: PerCallProfiling): boolean;
-export declare function shouldIncludeServerBreakdown(perCallOptions?: PerCallProfiling): boolean;
-export declare function generateId(): string;
-export declare function record(event: ProfilingEvent): void;
-/** Returns unsubscribe function. */
-export declare function onRecord(callback: RecordCallback): () => void;
-export declare function getAggregates(): Record<string, AggregatedStats>;
-export declare function getRecentEvents(): ProfilingEvent[];
-export declare function clear(): void;
-export {};
-//# sourceMappingURL=controller.d.ts.map