@qvac/sdk 0.19.0 → 0.20.0

package/src/electron-forge/index.cjs

@@ -2,8 +2,8 @@
  * @qvac/sdk/electron-forge
  *
  * Electron Forge plugin: bundles the QVAC worker, verifies its native addons,
- * then configures Electron Packager to tree-shake unused @qvac/* addons and
- * non-target prebuilds.
+ * then configures Electron Packager to tree-shake unused @qvac/* addons (along
+ * with their per-platform prebuild packages) and non-target prebuilds.
  *
  * macOS universal (`arch: "universal"`) is not supported — native addon
  * prebuilds are arch-specific. Build darwin-arm64 and darwin-x64 separately.
@@ -146,16 +146,45 @@ function findQvacScopeDir(startDir) {
 }
 
 /**
- * Discovers installed @qvac addon packages by scanning node_modules/@qvac
- * for packages that have `addon: true` in package.json.
+ * Reads the addon a per-platform prebuild package ships binaries for.
+ *
+ * Addons that split their prebuilds (`@qvac/tts-ggml` since 0.9.0, along with
+ * `@qvac/asr-ggml` 0.5.0 and `@qvac/audiogen-ggml` 0.4.0) publish the host's
+ * `.bare` in `@qvac/<addon>-<host>` (iOS flavours grouped as
+ * `@qvac/<addon>-ios`). Those packages carry no top-level `addon: true`;
+ * instead they embed an inner `addon/` package named after the meta addon.
+ * Returns that addon name, or null when `pkgDir` is not a platform package.
+ * Exposed for unit testing.
+ */
+function readPlatformPackageAddon(pkgDir) {
+  const addonPkgJsonPath = path.join(pkgDir, 'addon', 'package.json')
+  if (!fs.existsSync(addonPkgJsonPath)) return null
+
+  try {
+    const pkg = JSON.parse(fs.readFileSync(addonPkgJsonPath, 'utf8'))
+    if (pkg.addon === true && typeof pkg.name === 'string' && pkg.name.length > 0) {
+      return pkg.name
+    }
+  } catch (err) {
+    logger.warn(`Failed to parse ${addonPkgJsonPath}: ${err.message}`)
+  }
+  return null
+}
+
+/**
+ * Discovers installed @qvac packages by scanning node_modules/@qvac: the
+ * addons (`addon: true` in package.json) and the per-platform prebuild
+ * packages, each mapped to the addon it belongs to.
  */
 function discoverQvacAddonPackages(projectDir) {
+  const nothing = { addons: [], platformPackages: [] }
+
   let scopeDir
   try {
     scopeDir = findQvacScopeDir(projectDir)
   } catch (err) {
     logger.warn(err.message)
-    return []
+    return nothing
   }
 
   let entries
@@ -163,10 +192,11 @@ function discoverQvacAddonPackages(projectDir) {
     entries = fs.readdirSync(scopeDir)
   } catch (err) {
     logger.fsError('discoverQvacAddonPackages', err)
-    return []
+    return nothing
   }
 
-  const discovered = []
+  const addons = []
+  const platformPackages = []
 
   for (const name of entries) {
     const pkgDir = path.join(scopeDir, name)
@@ -175,18 +205,25 @@ function discoverQvacAddonPackages(projectDir) {
     const pkgJsonPath = path.join(pkgDir, 'package.json')
     if (!fs.existsSync(pkgJsonPath)) continue
 
+    const packageName = `@qvac/${name}`
     try {
       const pkg = JSON.parse(fs.readFileSync(pkgJsonPath, 'utf8'))
       if (pkg.addon === true) {
-        discovered.push(`@qvac/${name}`)
+        addons.push(packageName)
+        continue
       }
     } catch (err) {
       logger.warn(`Failed to parse ${pkgJsonPath}: ${err.message}`)
+      continue
     }
+
+    const addon = readPlatformPackageAddon(pkgDir)
+    if (addon !== null) platformPackages.push({ name: packageName, addon })
   }
 
-  discovered.sort()
-  return discovered
+  addons.sort()
+  platformPackages.sort((a, b) => a.name.localeCompare(b.name))
+  return { addons, platformPackages }
 }
 
 /**
@@ -203,20 +240,36 @@ function diffAddons(installed, required) {
 }
 
 /**
- * Computes the list of installed @qvac addons that aren't in `required`.
+ * Pure diff: per-platform prebuild packages whose addon is not in the
+ * required set. A platform package ships only its addon's binaries, so it
+ * follows that addon's include/exclude decision.
+ * Exposed for unit testing.
+ */
+function diffPlatformPackages(platformPackages, required) {
+  const requiredSet = new Set(required)
+  const exclusions = []
+  for (const { name, addon } of platformPackages) {
+    if (!requiredSet.has(addon)) exclusions.push(name)
+  }
+  return exclusions
+}
+
+/**
+ * Computes the list of installed @qvac addons that aren't in `required`,
+ * plus the per-platform prebuild packages of those excluded addons.
  * Logs include/exclude decisions for each discovered package.
  */
 function computeExclusions(required, projectDir) {
-  const installed = discoverQvacAddonPackages(projectDir)
+  const { addons, platformPackages } = discoverQvacAddonPackages(projectDir)
 
-  if (installed.length === 0) {
+  if (addons.length === 0) {
     logger.warn('No @qvac addon packages discovered. Skipping addon exclusions.')
     return []
   }
 
   const requiredSet = new Set(required)
   const exclusions = []
-  for (const pkg of installed) {
+  for (const pkg of addons) {
     if (requiredSet.has(pkg)) {
       logger.info(`Including required addon: ${pkg}`)
     } else {
@@ -224,6 +277,14 @@ function computeExclusions(required, projectDir) {
       exclusions.push(pkg)
     }
   }
+  for (const { name, addon } of platformPackages) {
+    if (requiredSet.has(addon)) {
+      logger.info(`Including platform package ${name} (prebuilds for ${addon})`)
+    } else {
+      logger.info(`Excluding platform package ${name} (prebuilds for unused addon ${addon})`)
+      exclusions.push(name)
+    }
+  }
   return exclusions
 }
 
@@ -594,6 +655,15 @@ async function runBundleAndVerify(commands, projectDir, options) {
     )
   }
 
+  // Narrowed prebuild checks are otherwise invisible in the log.
+  const narrowed = verifyResult.addons.filter(
+    (addon) => Array.isArray(addon.linkedHosts) && addon.linkedHosts.length < hosts.length
+  )
+  for (const addon of narrowed) {
+    const where = addon.linkedHosts.length === 0 ? 'no host' : addon.linkedHosts.join(', ')
+    logger.info(`verifyBundle: ${addon.name}@${addon.version} is linked on ${where}`)
+  }
+
   return bundleResult
 }
 
@@ -772,6 +842,8 @@ module.exports.QvacForgePluginError = QvacForgePluginError
 // Internal helpers exposed for unit tests. Not part of the stable API.
 module.exports.createIgnore = createIgnore
 module.exports.diffAddons = diffAddons
+module.exports.diffPlatformPackages = diffPlatformPackages
+module.exports.readPlatformPackageAddon = readPlatformPackageAddon
 module.exports.detectTargetHosts = detectTargetHosts
 module.exports.resolveHosts = resolveHosts
 module.exports.runBundleAndVerify = runBundleAndVerify

package/src/expo/plugins/patches/android-link.mjs

@@ -5,12 +5,15 @@
  * Otherwise, falls back to linking all installed addons.
  *
  * This file is copied over react-native-bare-kit/android/link.mjs
- * by withMobileBundle.ts during expo prebuild.
+ * by withMobileBundle.ts during expo prebuild. The resolver it imports is
+ * compiled from qvac-platform-addons.ts and installed beside this file as
+ * qvac-platform-addons.mjs.
  */
 import fs from 'fs'
 import path from 'path'
 import { fileURLToPath } from 'url'
 import link from 'bare-link'
+import { resolvePlatformAddonRoots } from './qvac-platform-addons.mjs'
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url))
 const projectRoot = path.join(__dirname, '..', '..', '..')
@@ -24,10 +27,12 @@ if (fs.existsSync(addonsDir)) {
 const manifestPath = path.join(projectRoot, 'qvac', 'addons.manifest.json')
 
 let pkg = null
+let addonNames = []
 if (fs.existsSync(manifestPath)) {
   try {
     const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'))
     const addons = Array.isArray(manifest.addons) ? manifest.addons : []
+    addonNames = addons
 
     if (addons.length > 0) {
       console.log(`[QVAC] Using addons manifest (${addons.length} addons): ${addons.join(', ')}`)
@@ -46,13 +51,17 @@ if (fs.existsSync(manifestPath)) {
   console.log('[QVAC] No addons manifest found, linking all addons')
 }
 
-for await (const resource of link(
-  projectRoot,
-  {
-    hosts: ['android-arm64', 'android-arm', 'android-ia32', 'android-x64'],
-    out: addonsDir
-  },
-  pkg
-)) {
+const hosts = ['android-arm64', 'android-arm', 'android-ia32', 'android-x64']
+
+for await (const resource of link(projectRoot, { hosts, out: addonsDir }, pkg)) {
   console.log('Wrote', resource)
 }
+
+// Split addons keep their binaries in a per-platform package; bare-link only
+// reaches the meta, which has shipped no prebuilds/ since the split.
+for (const addon of resolvePlatformAddonRoots(projectRoot, addonNames, 'android')) {
+  console.log(`[QVAC] Linking split addon ${addon.pkg.name} from its platform package`)
+  for await (const resource of link(addon.dir, { hosts, out: addonsDir }, addon.pkg)) {
+    console.log('Wrote', resource)
+  }
+}

package/src/expo/plugins/patches/ios-link.mjs

@@ -5,12 +5,15 @@
  * Otherwise, falls back to linking all installed addons.
  *
  * This file is copied over react-native-bare-kit/ios/link.mjs
- * by withMobileBundle.ts during expo prebuild.
+ * by withMobileBundle.ts during expo prebuild. The resolver it imports is
+ * compiled from qvac-platform-addons.ts and installed beside this file as
+ * qvac-platform-addons.mjs.
  */
 import fs from 'fs'
 import path from 'path'
 import { fileURLToPath } from 'url'
 import link from 'bare-link'
+import { resolvePlatformAddonRoots } from './qvac-platform-addons.mjs'
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url))
 const projectRoot = path.join(__dirname, '..', '..', '..')
@@ -24,10 +27,12 @@ if (fs.existsSync(addonsDir)) {
 const manifestPath = path.join(projectRoot, 'qvac', 'addons.manifest.json')
 
 let pkg = null
+let addonNames = []
 if (fs.existsSync(manifestPath)) {
   try {
     const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'))
     const addons = Array.isArray(manifest.addons) ? manifest.addons : []
+    addonNames = addons
 
     if (addons.length > 0) {
       console.log(`[QVAC] Using addons manifest (${addons.length} addons): ${addons.join(', ')}`)
@@ -46,13 +51,17 @@ if (fs.existsSync(manifestPath)) {
   console.log('[QVAC] No addons manifest found, linking all addons')
 }
 
-for await (const resource of link(
-  projectRoot,
-  {
-    hosts: ['ios-arm64', 'ios-arm64-simulator', 'ios-x64-simulator'],
-    out: addonsDir
-  },
-  pkg
-)) {
+const hosts = ['ios-arm64', 'ios-arm64-simulator', 'ios-x64-simulator']
+
+for await (const resource of link(projectRoot, { hosts, out: addonsDir }, pkg)) {
   console.log('Wrote', resource)
 }
+
+// Split addons keep their binaries in a per-platform package; bare-link only
+// reaches the meta, which has shipped no prebuilds/ since the split.
+for (const addon of resolvePlatformAddonRoots(projectRoot, addonNames, 'ios')) {
+  console.log(`[QVAC] Linking split addon ${addon.pkg.name} from its platform package`)
+  for await (const resource of link(addon.dir, { hosts, out: addonsDir }, addon.pkg)) {
+    console.log('Wrote', resource)
+  }
+}

package/src/expo/plugins/patches/qvac-platform-addons.ts

@@ -0,0 +1,124 @@
+/**
+ * Resolves split-addon platform packages from the meta package's `#host-addon`
+ * map. Linker, verify, and the missing-prebuild error all call this module so
+ * the slice name cannot drift from what the addon actually imports.
+ *
+ * Keep this file free of `@/` imports: the compiled JS is copied next to the
+ * patched `link.mjs` as `qvac-platform-addons.mjs`.
+ */
+import * as fs from 'fs'
+import * as path from 'path'
+
+export const HOST_ADDON_IMPORT = '#host-addon'
+
+const DEFAULT_ANDROID_CPU = 'arm64'
+
+export interface PlatformAddonRoot {
+  dir: string
+  pkg: { name?: string; version?: string; addon?: boolean }
+}
+
+export function resolvePlatformAddonRoots(
+  projectRoot: string,
+  addonNames: string[],
+  platform: string
+): PlatformAddonRoot[] {
+  const roots: PlatformAddonRoot[] = []
+  for (const name of addonNames) {
+    const root = resolvePlatformAddonRoot(projectRoot, name, platform)
+    if (root !== null) roots.push(root)
+  }
+  return roots
+}
+
+function resolvePlatformAddonRoot(
+  projectRoot: string,
+  metaName: string,
+  platform: string
+): PlatformAddonRoot | null {
+  const metaManifest = readManifest(packageDir(projectRoot, metaName))
+  if (metaManifest === null) return null
+
+  const platformPackage = resolveAddonPlatformPackage(
+    metaName,
+    metaManifest.imports?.[HOST_ADDON_IMPORT],
+    platform
+  )
+  if (platformPackage === null) return null
+
+  const addonDir = path.join(packageDir(projectRoot, platformPackage), 'addon')
+  const addonManifest = readManifest(addonDir)
+  if (addonManifest === null || addonManifest.addon !== true) return null
+  if (!fs.existsSync(path.join(addonDir, 'prebuilds'))) return null
+
+  return { dir: addonDir, pkg: addonManifest }
+}
+
+function packageDir(projectRoot: string, packageName: string): string {
+  return path.join(projectRoot, 'node_modules', ...packageName.split('/'))
+}
+
+interface AddonManifest {
+  name?: string
+  version?: string
+  addon?: boolean
+  imports?: Record<string, unknown>
+}
+
+function readManifest(dir: string): AddonManifest | null {
+  try {
+    const parsed: unknown = JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8'))
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) return null
+    return parsed as AddonManifest
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Package `#host-addon` names for `host`, if that name belongs to `metaName`.
+ * `host` is a Bare host (`android-arm64`, `ios-arm64-simulator`, `darwin-arm64`)
+ * or a mobile build target (`android`, `ios`).
+ */
+export function resolveAddonPlatformPackage(
+  metaName: string,
+  hostAddon: unknown,
+  host: string
+): string | null {
+  const name = resolvePlatformPackageName(hostAddon, host)
+  if (name === null) return null
+  if (!name.startsWith(`${metaName}-`)) return null
+  return name
+}
+
+/**
+ * First package name a `#host-addon` map points at for `host`.
+ * Android nests the package under its architecture; iOS is a flat list.
+ * A platform-only `android` target uses arm64, matching the current mobile host.
+ */
+export function resolvePlatformPackageName(hostAddon: unknown, host: string): string | null {
+  if (typeof host !== 'string' || host.length === 0) return null
+
+  const separator = host.indexOf('-')
+  const platform = separator === -1 ? host : host.slice(0, separator)
+  const cpu = separator === -1 ? '' : host.slice(separator + 1)
+
+  const branch = readBranch(hostAddon, platform)
+  const direct = packageName(branch)
+  if (direct !== null) return direct
+
+  const cpuKey = cpu.length > 0 ? cpu : DEFAULT_ANDROID_CPU
+  return packageName(readBranch(branch, cpuKey))
+}
+
+function packageName(candidate: unknown): string | null {
+  const name = Array.isArray(candidate) ? candidate[0] : candidate
+  if (typeof name !== 'string' || name.startsWith('.')) return null
+  return name
+}
+
+function readBranch(value: unknown, key: string): unknown {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) return undefined
+  if (!Object.hasOwn(value, key)) return undefined
+  return (value as Record<string, unknown>)[key]
+}