@qvac/sdk 0.11.0 → 0.12.1

package/dist/commands/bundle/index.js

@@ -0,0 +1,141 @@
+import fs, { promises as fsp } from "node:fs";
+import path from "node:path";
+import { createRequire } from "node:module";
+import { DEFAULT_HOSTS, DEFAULT_SDK_NAME } from "./constants.js";
+import { CONFIG_CANDIDATES, resolveConfigForProject, } from "../../client/config-loader/resolve-config.node.js";
+import { getClientLogger } from "../../logging/index.js";
+import { BareImportsMapNotFoundError } from "../../utils/errors-client.js";
+import { resolvePluginSpecifiers, parseBuiltinSpecifier, } from "./plugins.js";
+import { generateWorkerEntry } from "./entry-gen.js";
+import { runBarePack } from "./bare-pack.js";
+import { generateAddonsManifest } from "./manifest.js";
+const require = createRequire(import.meta.url);
+function resolveSdkPath(projectRoot, explicitSdkPath) {
+    if (explicitSdkPath) {
+        return path.isAbsolute(explicitSdkPath)
+            ? explicitSdkPath
+            : path.join(projectRoot, explicitSdkPath);
+    }
+    try {
+        const pkgJsonPath = require.resolve("@qvac/sdk/package.json", {
+            paths: [projectRoot],
+        });
+        return path.dirname(pkgJsonPath);
+    }
+    catch {
+        return path.join(projectRoot, "node_modules", "@qvac", "sdk");
+    }
+}
+async function resolveSdkName(sdkPath) {
+    const sdkPackageJsonPath = path.join(sdkPath, "package.json");
+    try {
+        if (fs.existsSync(sdkPackageJsonPath)) {
+            const content = await fsp.readFile(sdkPackageJsonPath, "utf8");
+            const pkg = JSON.parse(content);
+            if (pkg.name)
+                return pkg.name;
+        }
+    }
+    catch {
+        // Fall through to default
+    }
+    return DEFAULT_SDK_NAME;
+}
+function resolveImportsMapPath(sdkPath, sdkName) {
+    const importsMapPath = path.join(sdkPath, "bare-imports.json");
+    if (fs.existsSync(importsMapPath)) {
+        return importsMapPath;
+    }
+    throw new BareImportsMapNotFoundError(sdkName, importsMapPath);
+}
+function createCommandLogger(options) {
+    if (options.quiet) {
+        return getClientLogger({ level: "error", enableConsole: false });
+    }
+    if (options.verbose) {
+        return getClientLogger({ level: "debug" });
+    }
+    return getClientLogger();
+}
+export async function bundleSdk(options = {}) {
+    const startTime = Date.now();
+    const projectRoot = options.projectRoot ?? process.cwd();
+    const outputDir = path.join(projectRoot, "qvac");
+    const entryPath = path.join(outputDir, "worker.entry.mjs");
+    const bundlePath = path.join(outputDir, "worker.bundle.js");
+    const logger = createCommandLogger(options);
+    logger.info("🔧 QVAC SDK Worker Bundler\n");
+    const { configPath, config } = await resolveConfigForProject(projectRoot, options.configPath);
+    if (configPath) {
+        logger.info(`📄 Config: ${path.relative(projectRoot, configPath)}`);
+    }
+    else {
+        logger.info("📄 Config: (none)");
+        logger.warn("No config file found — continuing with defaults.");
+        logger.info("   To customize bundling, create one of:\n" +
+            CONFIG_CANDIDATES.map((c) => `     - ${c}`).join("\n") +
+            "\n");
+    }
+    const sdkPath = resolveSdkPath(projectRoot, options.sdkPath);
+    const sdkName = await resolveSdkName(sdkPath);
+    logger.info(`📦 SDK: ${sdkName}`);
+    logger.debug(`   Path: ${sdkPath}`);
+    const importsMapPath = resolveImportsMapPath(sdkPath, sdkName);
+    const pluginSpecifiers = resolvePluginSpecifiers(config, sdkName, logger);
+    logger.info(`\n📦 Plugins to include (${pluginSpecifiers.length}):`);
+    for (const spec of pluginSpecifiers) {
+        const label = parseBuiltinSpecifier(spec, sdkName)
+            ? "✓ built-in"
+            : "⊕ custom";
+        logger.info(`   ${label}: ${spec}`);
+    }
+    const hosts = options.hosts && options.hosts.length > 0 ? options.hosts : DEFAULT_HOSTS;
+    const deferModules = options.defer ?? [];
+    await fsp.mkdir(outputDir, { recursive: true });
+    logger.info("\n📝 Generating worker entry...");
+    const workerEntry = generateWorkerEntry(pluginSpecifiers, sdkName);
+    await fsp.writeFile(entryPath, workerEntry, "utf8");
+    logger.info(`   Created: ${path.relative(projectRoot, entryPath)}`);
+    logger.info(`   Using: ${path.relative(projectRoot, importsMapPath)}`);
+    logger.info("\n🔨 Bundling with bare-pack...");
+    logger.debug(`   Hosts: ${hosts.join(", ")}`);
+    if (deferModules.length > 0) {
+        logger.debug(`   Deferred: ${deferModules.join(", ")}`);
+    }
+    await runBarePack({
+        entryPath,
+        outputPath: bundlePath,
+        hosts,
+        importsMapPath,
+        deferModules,
+        quiet: options.quiet === true,
+        logger,
+    });
+    const stats = await fsp.stat(bundlePath);
+    const sizeKB = (stats.size / 1024).toFixed(1);
+    logger.info(`\n✅ Bundle created: ${path.relative(projectRoot, bundlePath)}`);
+    logger.info(`   Size: ${sizeKB} KB`);
+    const manifestResult = await generateAddonsManifest({
+        bundlePath,
+        outputDir,
+        projectRoot,
+        logger,
+    });
+    const elapsed = ((Date.now() - startTime) / 1000).toFixed(2);
+    logger.info(`\n🎉 Done in ${elapsed}s!\n`);
+    logger.info("Generated files:");
+    logger.info("  - qvac/worker.entry.mjs    (standalone worker with RPC + lifecycle)");
+    logger.info("  - qvac/worker.bundle.js    (mobile bundle for Expo/React Native BareKit)");
+    logger.info("  - qvac/addons.manifest.json\n");
+    logger.info("Mobile: Expo plugin auto-configures worker.bundle.js");
+    logger.info("Standalone: Import qvac/worker.entry.mjs for full worker with RPC\n");
+    return {
+        bundlePath,
+        plugins: pluginSpecifiers,
+        addons: manifestResult.addons,
+        entryPaths: {
+            worker: entryPath,
+        },
+        manifestPath: manifestResult.manifestPath,
+    };
+}

package/dist/commands/bundle/manifest.d.ts

@@ -0,0 +1,21 @@
+import type { Logger } from "../../logging/types";
+interface BarePackHeader {
+    id?: string;
+    resolutions?: Record<string, unknown>;
+}
+interface GenerateAddonsManifestOptions {
+    bundlePath: string;
+    outputDir: string;
+    projectRoot: string;
+    logger: Logger;
+}
+interface GenerateAddonsManifestResult {
+    manifestPath: string;
+    addons: string[];
+}
+export declare function extractPackedString(bundleJsText: string): string;
+export declare function extractBarePackHeader(packed: string): BarePackHeader;
+export declare function buildNestedPathIndex(resolutions: Record<string, unknown>, projectRoot: string): Map<string, Set<string>>;
+export declare function generateAddonsManifest(options: GenerateAddonsManifestOptions): Promise<GenerateAddonsManifestResult>;
+export {};
+//# sourceMappingURL=manifest.d.ts.map

package/dist/commands/bundle/manifest.js

@@ -0,0 +1,193 @@
+import fs, { promises as fsp } from "node:fs";
+import path from "node:path";
+export function extractPackedString(bundleJsText) {
+    const idx = bundleJsText.indexOf("module.exports");
+    if (idx === -1) {
+        throw new Error("bundle does not contain 'module.exports'");
+    }
+    const eq = bundleJsText.indexOf("=", idx);
+    if (eq === -1) {
+        throw new Error("could not find '=' after module.exports");
+    }
+    let i = eq + 1;
+    while (i < bundleJsText.length && /\s/.test(bundleJsText[i] ?? ""))
+        i++;
+    const quote = bundleJsText[i];
+    if (quote !== '"' && quote !== "'") {
+        throw new Error("export value is not a string literal");
+    }
+    i++;
+    let out = "";
+    let esc = false;
+    for (; i < bundleJsText.length; i++) {
+        const ch = bundleJsText[i];
+        if (esc) {
+            switch (ch) {
+                case "n":
+                    out += "\n";
+                    break;
+                case "r":
+                    out += "\r";
+                    break;
+                case "t":
+                    out += "\t";
+                    break;
+                case "b":
+                    out += "\b";
+                    break;
+                case "f":
+                    out += "\f";
+                    break;
+                case "v":
+                    out += "\v";
+                    break;
+                case "\\":
+                    out += "\\";
+                    break;
+                case '"':
+                    out += '"';
+                    break;
+                case "'":
+                    out += "'";
+                    break;
+                case "x": {
+                    const hex = bundleJsText.slice(i + 1, i + 3);
+                    if (!/^[0-9a-fA-F]{2}$/.test(hex))
+                        throw new Error("bad \\x escape");
+                    out += String.fromCharCode(parseInt(hex, 16));
+                    i += 2;
+                    break;
+                }
+                case "u": {
+                    const hex = bundleJsText.slice(i + 1, i + 5);
+                    if (!/^[0-9a-fA-F]{4}$/.test(hex))
+                        throw new Error("bad \\u escape");
+                    out += String.fromCharCode(parseInt(hex, 16));
+                    i += 4;
+                    break;
+                }
+                default:
+                    out += ch;
+            }
+            esc = false;
+            continue;
+        }
+        if (ch === "\\") {
+            esc = true;
+            continue;
+        }
+        if (ch === quote)
+            break;
+        out += ch;
+    }
+    if (i >= bundleJsText.length) {
+        throw new Error("unterminated string literal");
+    }
+    return out;
+}
+export function extractBarePackHeader(packed) {
+    const firstNL = packed.indexOf("\n");
+    if (firstNL === -1) {
+        throw new Error("packed string missing first newline separator");
+    }
+    const jsonStart = packed.indexOf("{", firstNL + 1);
+    if (jsonStart === -1) {
+        throw new Error("could not find header JSON start in packed string");
+    }
+    let i = jsonStart;
+    let depth = 0;
+    let inStr = false;
+    let esc = false;
+    for (; i < packed.length; i++) {
+        const ch = packed[i];
+        if (inStr) {
+            if (esc)
+                esc = false;
+            else if (ch === "\\")
+                esc = true;
+            else if (ch === '"')
+                inStr = false;
+            continue;
+        }
+        if (ch === '"')
+            inStr = true;
+        else if (ch === "{")
+            depth++;
+        else if (ch === "}") {
+            depth--;
+            if (depth === 0) {
+                i++;
+                break;
+            }
+        }
+    }
+    if (depth !== 0) {
+        throw new Error("unbalanced braces while extracting header JSON");
+    }
+    return JSON.parse(packed.slice(jsonStart, i));
+}
+const NODE_MODULES_RE = /\/node_modules\/(@[^/]+\/[^/]+|[^/]+)(?=\/)/g;
+export function buildNestedPathIndex(resolutions, projectRoot) {
+    const index = new Map();
+    for (const key of Object.keys(resolutions)) {
+        for (const match of key.matchAll(NODE_MODULES_RE)) {
+            const pkgName = match[1];
+            if (!pkgName)
+                continue;
+            const idx = match.index;
+            if (idx === undefined)
+                continue;
+            const marker = `/node_modules/${pkgName}/`;
+            const candidate = path.join(projectRoot, key.slice(1, idx + marker.length), "package.json");
+            let set = index.get(pkgName);
+            if (!set) {
+                set = new Set();
+                index.set(pkgName, set);
+            }
+            set.add(candidate);
+        }
+    }
+    return index;
+}
+export async function generateAddonsManifest(options) {
+    const { bundlePath, outputDir, projectRoot, logger } = options;
+    logger.info("\n📦 Generating addons manifest...");
+    const bundleJsText = await fsp.readFile(bundlePath, "utf8");
+    const packed = extractPackedString(bundleJsText);
+    const header = extractBarePackHeader(packed);
+    const resolutions = header.resolutions ?? {};
+    const pathsByPackage = buildNestedPathIndex(resolutions, projectRoot);
+    const addons = [];
+    for (const [pkgName, candidates] of pathsByPackage) {
+        let pkgJson = null;
+        for (const candidate of candidates) {
+            try {
+                if (fs.existsSync(candidate)) {
+                    pkgJson = JSON.parse(await fsp.readFile(candidate, "utf8"));
+                    break;
+                }
+            }
+            catch (err) {
+                logger.warn(`   Could not read ${candidate}: ${err.message}`);
+            }
+        }
+        if (pkgJson?.addon === true) {
+            addons.push(pkgName);
+        }
+    }
+    addons.sort();
+    const bundleId = typeof header.id === "string" && header.id.length > 0
+        ? header.id
+        : "unknown";
+    const manifest = {
+        version: 1,
+        bundleId,
+        addons,
+    };
+    const manifestPath = path.join(outputDir, "addons.manifest.json");
+    await fsp.writeFile(manifestPath, JSON.stringify(manifest, null, 2) + "\n");
+    logger.info(`   Found ${pathsByPackage.size} packages in bundle graph`);
+    logger.info(`   Identified ${addons.length} native addons: ${addons.join(", ") || "(none)"}`);
+    logger.info(`   Wrote ${manifestPath}`);
+    return { manifestPath, addons };
+}

package/dist/commands/bundle/plugins.d.ts

@@ -0,0 +1,9 @@
+import type { Logger } from "../../logging/types";
+import type { QvacConfig } from "../../schemas/sdk-config";
+export declare function buildBuiltinSpecifier(sdkName: string, suffix: string): string;
+export declare function parseBuiltinSpecifier(specifier: string, sdkName: string): {
+    suffix: string;
+    exportName: string;
+} | null;
+export declare function resolvePluginSpecifiers(config: QvacConfig, sdkName: string, logger: Logger): string[];
+//# sourceMappingURL=plugins.d.ts.map

package/dist/commands/bundle/plugins.js

@@ -0,0 +1,51 @@
+import { BUILTIN_PLUGINS, BUILTIN_SUFFIXES } from "./constants.js";
+import { InvalidPluginSpecifierError } from "../../utils/errors-client.js";
+export function buildBuiltinSpecifier(sdkName, suffix) {
+    return `${sdkName}/${suffix}/plugin`;
+}
+export function parseBuiltinSpecifier(specifier, sdkName) {
+    const prefix = `${sdkName}/`;
+    const pluginSuffix = "/plugin";
+    if (specifier.startsWith(prefix) && specifier.endsWith(pluginSuffix)) {
+        const middle = specifier.slice(prefix.length, -pluginSuffix.length);
+        const info = BUILTIN_PLUGINS[middle];
+        if (!middle.includes("/") && info) {
+            return { suffix: middle, exportName: info.exportName };
+        }
+    }
+    return null;
+}
+export function resolvePluginSpecifiers(config, sdkName, logger) {
+    let plugins = config.plugins ?? [];
+    if (plugins.length === 0) {
+        const allBuiltins = BUILTIN_SUFFIXES.map((suffix) => buildBuiltinSpecifier(sdkName, suffix));
+        logger.warn("No plugins specified — bundling ALL built-in plugins.");
+        logger.info("   For smaller bundles, add a 'plugins' array to qvac.config.*\n");
+        plugins = allBuiltins;
+    }
+    const uniquePlugins = [...new Set(plugins)];
+    const resolved = [];
+    const customPlugins = [];
+    const errors = [];
+    for (const specifier of uniquePlugins) {
+        const builtin = parseBuiltinSpecifier(specifier, sdkName);
+        if (builtin) {
+            resolved.push(specifier);
+        }
+        else {
+            if (!specifier.endsWith("/plugin")) {
+                errors.push(specifier);
+            }
+            else {
+                customPlugins.push(specifier);
+            }
+        }
+    }
+    if (errors.length > 0) {
+        throw new InvalidPluginSpecifierError(errors);
+    }
+    if (customPlugins.length > 0) {
+        logger.info(`📦 Custom plugins: ${customPlugins.join(", ")}`);
+    }
+    return [...resolved, ...customPlugins];
+}

package/dist/commands/index.d.ts

@@ -0,0 +1,5 @@
+export { bundleSdk } from "./bundle/index";
+export type { BundleSdkOptions, BundleSdkResult } from "./bundle/index";
+export { verifyBundle, hasErrors, hasWarnings, formatVerifyBundleResult, } from "./verify/index";
+export type { VerifyBundleOptions, VerifyBundleResult, VerifyBundleIssue, } from "./verify/index";
+//# sourceMappingURL=index.d.ts.map

package/dist/commands/index.js

@@ -0,0 +1,2 @@
+export { bundleSdk } from "./bundle/index.js";
+export { verifyBundle, hasErrors, hasWarnings, formatVerifyBundleResult, } from "./verify/index.js";

package/dist/commands/verify/abi.d.ts

@@ -0,0 +1,52 @@
+import { type NativeAddon } from "./addon-source";
+export interface BareRuntime {
+    version: string;
+    source: "flag" | "config" | "bare-runtime" | "bare";
+}
+export interface UnresolvedBareRuntime {
+    reason: string;
+    triedPaths: string[];
+}
+export interface ResolveBareRuntimeOptions {
+    projectRoot: string;
+    explicitVersion?: string;
+    explicitSource?: "flag" | "config";
+}
+export type BareRuntimeResolution = {
+    resolved: true;
+    runtime: BareRuntime;
+} | {
+    resolved: false;
+    error: UnresolvedBareRuntime;
+};
+export interface AbiMismatchIssue {
+    code: "abi-mismatch";
+    level: "error";
+    addon: string;
+    message: string;
+    enginesBare: string;
+    runtimeVersion: string;
+}
+export interface UnknownRuntimeIssue {
+    code: "unknown-runtime-version";
+    level: "warning";
+    message: string;
+    triedPaths: string[];
+}
+export interface MalformedEnginesBareIssue {
+    code: "malformed-engines-bare";
+    level: "warning";
+    addon: string;
+    enginesBare: string;
+    message: string;
+}
+export type AbiIssue = AbiMismatchIssue | UnknownRuntimeIssue | MalformedEnginesBareIssue;
+export interface CheckAbiOptions {
+    addons: NativeAddon[];
+    runtime: BareRuntimeResolution;
+}
+export declare function resolveBareRuntime(options: ResolveBareRuntimeOptions): Promise<BareRuntimeResolution>;
+export declare function normalizeVersion(value: string): string | null;
+export declare function formatConfigLabel(projectRoot: string, configPath?: string): string;
+export declare function checkAbi(options: CheckAbiOptions): AbiIssue[];
+//# sourceMappingURL=abi.d.ts.map

package/dist/commands/verify/abi.js

@@ -0,0 +1,125 @@
+import { promises as fsp } from "node:fs";
+import path from "node:path";
+import semver from "semver";
+import { formatAddonId } from "./addon-source.js";
+const RUNTIME_PACKAGES = [
+    { source: "bare-runtime", packageName: "bare-runtime" },
+    { source: "bare", packageName: "bare" },
+];
+export async function resolveBareRuntime(options) {
+    if (options.explicitVersion) {
+        // Caller (verifyBundle) pre-validates explicitVersion via normalizeVersion.
+        return {
+            resolved: true,
+            runtime: {
+                version: normalizeVersion(options.explicitVersion),
+                source: options.explicitSource ?? "flag",
+            },
+        };
+    }
+    const tried = [];
+    for (const candidate of RUNTIME_PACKAGES) {
+        const pkgJsonPath = path.join(options.projectRoot, "node_modules", candidate.packageName, "package.json");
+        tried.push(pkgJsonPath);
+        const version = await tryReadRuntimeVersion(pkgJsonPath);
+        if (version) {
+            return {
+                resolved: true,
+                runtime: { version, source: candidate.source },
+            };
+        }
+    }
+    return {
+        resolved: false,
+        error: {
+            reason: "Unable to detect installed Bare runtime version",
+            triedPaths: tried,
+        },
+    };
+}
+async function tryReadRuntimeVersion(pkgJsonPath) {
+    let raw;
+    try {
+        raw = await fsp.readFile(pkgJsonPath, "utf8");
+    }
+    catch {
+        return null;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        return null;
+    }
+    const version = parsed["version"];
+    return typeof version === "string" ? normalizeVersion(version) : null;
+}
+export function normalizeVersion(value) {
+    const coerced = semver.coerce(value, { includePrerelease: true });
+    return coerced ? coerced.version : null;
+}
+export function formatConfigLabel(projectRoot, configPath) {
+    if (!configPath)
+        return "qvac.config";
+    const rel = path.relative(projectRoot, configPath);
+    if (!rel || rel.startsWith("..") || path.isAbsolute(rel))
+        return configPath;
+    return rel;
+}
+export function checkAbi(options) {
+    const { addons, runtime } = options;
+    const addonsWithEngines = addons.filter((addon) => addon.enginesBare !== undefined);
+    if (addonsWithEngines.length === 0)
+        return [];
+    const issues = [];
+    const checkable = [];
+    for (const addon of addonsWithEngines) {
+        const range = addon.enginesBare;
+        if (!range)
+            continue;
+        if (!semver.validRange(range)) {
+            issues.push({
+                code: "malformed-engines-bare",
+                level: "warning",
+                addon: formatAddonId(addon),
+                enginesBare: range,
+                message: `${formatAddonId(addon)} declares engines.bare "${range}", which is ` +
+                    "not a valid semver range. ABI check skipped for this addon. " +
+                    "Report this to the addon maintainer.",
+            });
+            continue;
+        }
+        checkable.push({ addon, range });
+    }
+    if (checkable.length === 0)
+        return issues;
+    if (!runtime.resolved) {
+        issues.push({
+            code: "unknown-runtime-version",
+            level: "warning",
+            message: `${runtime.error.reason}. ABI checks skipped for ${checkable.length} ` +
+                `addon${checkable.length === 1 ? "" : "s"}. ` +
+                "Pass bareRuntimeVersion to enable strict ABI verification.",
+            triedPaths: runtime.error.triedPaths,
+        });
+        return issues;
+    }
+    for (const { addon, range } of checkable) {
+        if (semver.satisfies(runtime.runtime.version, range))
+            continue;
+        issues.push({
+            code: "abi-mismatch",
+            level: "error",
+            addon: formatAddonId(addon),
+            enginesBare: range,
+            runtimeVersion: runtime.runtime.version,
+            message: `${formatAddonId(addon)} requires bare ${range}, ` +
+                `runtime is ${runtime.runtime.version} (from ${runtime.runtime.source}).`,
+        });
+    }
+    return issues;
+}

package/dist/commands/verify/addon-source.d.ts

@@ -0,0 +1,43 @@
+export type AddonSourceKind = "bare-pack-bundle" | "node-modules";
+export interface NativeAddon {
+    name: string;
+    version?: string;
+    packageJsonPath: string;
+    packageRoot: string;
+    enginesBare?: string;
+}
+export interface AddonPackageJson {
+    name?: string;
+    version?: string;
+    addon?: boolean;
+    engines?: {
+        bare?: string;
+    };
+}
+export interface ReadAddonPackageJsonOptions {
+    packageJsonPath: string;
+    expectedName?: string;
+}
+export interface InvalidPackageJsonRecord {
+    packageJsonPath: string;
+    expectedName?: string;
+    reason: string;
+}
+export interface ReadAddonPackageJsonResult {
+    found: boolean;
+    isAddon: boolean;
+    invalid?: InvalidPackageJsonRecord;
+    addon?: NativeAddon;
+}
+export declare function readAddonPackageJson(options: ReadAddonPackageJsonOptions): Promise<ReadAddonPackageJsonResult>;
+export interface CollectDiagnostics {
+    invalidPackageJsons: InvalidPackageJsonRecord[];
+    emptyResolutions: boolean;
+}
+export declare function createCollectDiagnostics(): CollectDiagnostics;
+export declare function formatAddonId(addon: {
+    name: string;
+    version?: string;
+}): string;
+export declare function deduplicateAddons(addons: NativeAddon[]): NativeAddon[];
+//# sourceMappingURL=addon-source.d.ts.map