@lloyal-labs/lloyal.node 1.0.3-alpha

package/lib/index.js

@@ -0,0 +1,121 @@
+const path = require('path');
+const binary = require('node-gyp-build')(path.join(__dirname, '..'));
+
+/**
+ * liblloyal-node - Thin N-API wrapper over liblloyal
+ *
+ * Exposes raw llama.cpp inference primitives for Node.js.
+ * Primary use case: Integration testing for tsampler.
+ *
+ * @example
+ * ```js
+ * const { createContext, withLogits } = require('lloyal.node');
+ *
+ * const ctx = await createContext({
+ *   modelPath: './model.gguf',
+ *   nCtx: 2048,
+ *   nThreads: 4
+ * });
+ *
+ * // Tokenize
+ * const tokens = await ctx.tokenize("Hello world");
+ *
+ * // Decode
+ * await ctx.decode(tokens, 0);
+ *
+ * // Safe logits access (Runtime Borrow Checker pattern)
+ * const entropy = await withLogits(ctx, (logits) => {
+ *   // logits is valid here - use synchronously only!
+ *   return computeEntropy(logits);
+ * });
+ *
+ * // Or with native reference implementations (for testing)
+ * const nativeEntropy = ctx.computeEntropy();
+ * const token = ctx.greedySample();
+ *
+ * // Cleanup
+ * ctx.dispose();
+ * ```
+ */
+
+/**
+ * Safe logits access with Runtime Borrow Checker pattern
+ *
+ * Ensures logits are only accessed synchronously within the callback.
+ * The callback MUST NOT:
+ * - Store the logits reference
+ * - Return a Promise (will throw)
+ * - Call decode() (would invalidate logits)
+ *
+ * This is a "runtime borrow checker" - it prevents async mutations
+ * while you're working with borrowed logits.
+ *
+ * @template T
+ * @param {SessionContext} ctx - The session context
+ * @param {(logits: Float32Array) => T} fn - Synchronous callback that uses logits
+ * @returns {T} The result from the callback
+ * @throws {Error} If callback returns a Promise (async usage not allowed)
+ *
+ * @example
+ * ```js
+ * // Safe: synchronous computation
+ * const entropy = withLogits(ctx, (logits) => {
+ *   let sum = 0;
+ *   for (let i = 0; i < logits.length; i++) {
+ *     sum += Math.exp(logits[i]);
+ *   }
+ *   return Math.log(sum);
+ * });
+ *
+ * // ERROR: callback returns Promise (will throw)
+ * withLogits(ctx, async (logits) => {
+ *   await something();  // NOT ALLOWED
+ *   return logits[0];
+ * });
+ * ```
+ */
+function withLogits(ctx, fn) {
+  // Get logits (memoized - same buffer if called twice in same step)
+  const logits = ctx.getLogits();
+
+  // Execute user callback with logits
+  const result = fn(logits);
+
+  // Detect async usage (not allowed - logits would be invalidated)
+  if (result && typeof result.then === 'function') {
+    throw new Error(
+      'withLogits callback must be synchronous. ' +
+      'Returning a Promise is not allowed because logits become invalid after decode(). ' +
+      'Complete all logits processing synchronously within the callback.'
+    );
+  }
+
+  return result;
+}
+
+module.exports = {
+  /**
+   * Create a new inference context
+   *
+   * @param {Object} options
+   * @param {string} options.modelPath - Path to .gguf model file
+   * @param {number} [options.nCtx=2048] - Context size
+   * @param {number} [options.nThreads=4] - Number of threads
+   * @returns {Promise<SessionContext>}
+   */
+  createContext: async (options) => {
+    // For now, createContext is synchronous in C++
+    // Wrap in Promise for future async model loading
+    return binary.createContext(options);
+  },
+
+  /**
+   * Safe logits access with Runtime Borrow Checker pattern
+   *
+   * Ensures logits are only accessed synchronously within the callback.
+   * See function JSDoc for full documentation.
+   */
+  withLogits,
+
+  SessionContext: binary.SessionContext
+};

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "@lloyal-labs/lloyal.node",
+  "version": "1.0.3-alpha",
+  "description": "Node.js client for liblloyal+llama.cpp",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "gypfile": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "download-models": "bash scripts/download-test-models.sh",
+    "install": "node scripts/install.js",
+    "build": "node scripts/build.js",
+    "build:debug": "cmake-js compile --debug",
+    "rebuild": "cmake-js rebuild",
+    "clean": "cmake-js clean && rm -rf build_test/",
+    "version": "node scripts/sync-versions.js && git add -A",
+    "docs": "npx typedoc",
+    "test": "npm run test:api && npm run test:e2e",
+    "test:api": "node test/api.js",
+    "test:e2e": "node test/e2e.js",
+    "example": "node examples/chat/chat.mjs"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lloyal-ai/lloyal.node.git"
+  },
+  "keywords": [
+    "llama",
+    "llama.cpp",
+    "liblloyal",
+    "napi",
+    "native",
+    "inference",
+    "llm"
+  ],
+  "author": "lloyal.ai",
+  "license": "Apache-2.0",
+  "type": "commonjs",
+  "bugs": {
+    "url": "https://github.com/lloyal-ai/lloyal.node/issues"
+  },
+  "homepage": "https://github.com/lloyal-ai/lloyal.node#readme",
+  "dependencies": {
+    "node-addon-api": "^8.5.0",
+    "node-gyp-build": "^4.8.4"
+  },
+  "devDependencies": {
+    "cmake-js": "^7.4.0",
+    "glob": "^11.0.0",
+    "typedoc": "^0.27.5"
+  },
+  "optionalDependencies": {
+    "@lloyal-labs/lloyal.node-darwin-arm64": "1.0.3-alpha",
+    "@lloyal-labs/lloyal.node-darwin-x64": "1.0.3-alpha",
+    "@lloyal-labs/lloyal.node-linux-arm64": "1.0.3-alpha",
+    "@lloyal-labs/lloyal.node-linux-arm64-cuda": "1.0.3-alpha",
+    "@lloyal-labs/lloyal.node-linux-arm64-vulkan": "1.0.3-alpha",
+    "@lloyal-labs/lloyal.node-linux-x64": "1.0.3-alpha",
+    "@lloyal-labs/lloyal.node-linux-x64-cuda": "1.0.3-alpha",
+    "@lloyal-labs/lloyal.node-linux-x64-vulkan": "1.0.3-alpha",
+    "@lloyal-labs/lloyal.node-win32-arm64": "1.0.3-alpha",
+    "@lloyal-labs/lloyal.node-win32-arm64-vulkan": "1.0.3-alpha",
+    "@lloyal-labs/lloyal.node-win32-x64": "1.0.3-alpha",
+    "@lloyal-labs/lloyal.node-win32-x64-cuda": "1.0.3-alpha",
+    "@lloyal-labs/lloyal.node-win32-x64-vulkan": "1.0.3-alpha"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "files": [
+    "lib/",
+    "scripts/"
+  ]
+}

package/scripts/build.js

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+/**
+ * Build script for lloyal.node
+ * 
+ * Wraps cmake-js with GPU backend detection from LLOYAL_GPU environment variable.
+ * 
+ * Usage:
+ *   npm run build                     # CPU/Metal (auto-detected)
+ *   LLOYAL_GPU=cuda npm run build     # CUDA
+ *   LLOYAL_GPU=vulkan npm run build   # Vulkan
+ *   LLOYAL_GPU=metal npm run build    # Metal (macOS only)
+ */
+
+const { execSync } = require('child_process');
+const os = require('os');
+
+const PLATFORM = process.platform;
+const gpuBackend = process.env.LLOYAL_GPU?.toLowerCase();
+
+// Build cmake-js command with appropriate flags
+const cmakeFlags = [];
+
+if (gpuBackend === 'cuda') {
+  cmakeFlags.push('--CDGGML_CUDA=ON');
+  console.log('[lloyal.node] GPU backend: CUDA');
+} else if (gpuBackend === 'vulkan') {
+  cmakeFlags.push('--CDGGML_VULKAN=ON');
+  console.log('[lloyal.node] GPU backend: Vulkan');
+} else if (gpuBackend === 'metal') {
+  cmakeFlags.push('--CDGGML_METAL=ON');
+  console.log('[lloyal.node] GPU backend: Metal');
+} else if (PLATFORM === 'darwin') {
+  // Metal is auto-enabled on macOS by llama.cpp
+  console.log('[lloyal.node] GPU backend: Metal (auto-enabled on macOS)');
+} else {
+  console.log('[lloyal.node] GPU backend: CPU only');
+}
+
+const buildCmd = `npx cmake-js compile ${cmakeFlags.join(' ')}`.trim();
+console.log(`[lloyal.node] Running: ${buildCmd}`);
+
+try {
+  execSync(buildCmd, {
+    cwd: __dirname + '/..',
+    stdio: 'inherit'
+  });
+  console.log('[lloyal.node] ✅ Build successful!');
+} catch (error) {
+  console.error('[lloyal.node] ❌ Build failed');
+  process.exit(1);
+}

package/scripts/create-platform-package.js

@@ -0,0 +1,152 @@
+#!/usr/bin/env node
+/**
+ * Create platform-specific package for prebuilt binaries
+ *
+ * Usage: node scripts/create-platform-package.js <package-name> <os> <arch>
+ * Example: node scripts/create-platform-package.js darwin-arm64 macos-14 arm64
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const [packageName, osRunner, arch] = process.argv.slice(2);
+
+if (!packageName || !osRunner || !arch) {
+  console.error('Usage: node create-platform-package.js <package-name> <os-runner> <arch>');
+  console.error('Example: node create-platform-package.js darwin-arm64 macos-14 arm64');
+  process.exit(1);
+}
+
+const ROOT = path.join(__dirname, '..');
+const BUILD_DIR = path.join(ROOT, 'build', 'Release');
+const PACKAGES_DIR = path.join(ROOT, 'packages');
+const PKG_DIR = path.join(PACKAGES_DIR, packageName);
+const BIN_DIR = path.join(PKG_DIR, 'bin');
+
+// Determine OS and CPU for package.json
+const OS_MAP = {
+  'macos-14': 'darwin',
+  'macos-13': 'darwin',
+  'ubuntu-22.04': 'linux',
+  'windows-2022': 'win32'
+};
+
+const osName = OS_MAP[osRunner] || process.platform;
+
+console.log(`\n=== Creating platform package: @lloyal-labs/lloyal.node-${packageName} ===\n`);
+
+// Create directories
+fs.mkdirSync(BIN_DIR, { recursive: true });
+
+// Copy binaries
+console.log('Copying binaries...');
+
+// N-API binary
+const nodeBinary = path.join(BUILD_DIR, 'lloyal.node');
+if (!fs.existsSync(nodeBinary)) {
+  console.error(`❌ Error: lloyal.node not found at ${nodeBinary}`);
+  console.error('Available files in build/Release:');
+  if (fs.existsSync(BUILD_DIR)) {
+    fs.readdirSync(BUILD_DIR).forEach(f => console.error(`  - ${f}`));
+  } else {
+    console.error('  (build/Release directory does not exist)');
+  }
+  process.exit(1);
+}
+
+fs.copyFileSync(nodeBinary, path.join(BIN_DIR, 'lloyal.node'));
+console.log(`  ✓ Copied lloyal.node`);
+
+// Shared libraries (platform-specific)
+if (osName === 'darwin') {
+  const dylib = path.join(BUILD_DIR, 'libllama.dylib');
+  if (fs.existsSync(dylib)) {
+    fs.copyFileSync(dylib, path.join(BIN_DIR, 'libllama.dylib'));
+    console.log(`  ✓ Copied libllama.dylib`);
+  } else {
+    console.warn(`  ⚠️  libllama.dylib not found (optional)`);
+  }
+} else if (osName === 'linux') {
+  const so = path.join(BUILD_DIR, 'libllama.so');
+  if (fs.existsSync(so)) {
+    fs.copyFileSync(so, path.join(BIN_DIR, 'libllama.so'));
+    console.log(`  ✓ Copied libllama.so`);
+  } else {
+    console.warn(`  ⚠️  libllama.so not found (optional)`);
+  }
+} else if (osName === 'win32') {
+  // Copy all DLLs
+  const dlls = fs.readdirSync(BUILD_DIR).filter(f => f.endsWith('.dll'));
+  if (dlls.length > 0) {
+    dlls.forEach(dll => {
+      fs.copyFileSync(
+        path.join(BUILD_DIR, dll),
+        path.join(BIN_DIR, dll)
+      );
+      console.log(`  ✓ Copied ${dll}`);
+    });
+  } else {
+    console.warn(`  ⚠️  No DLLs found in build/Release (optional)`);
+  }
+}
+
+// Create package.json from template
+console.log('\nGenerating package.json...');
+const mainPackageJson = require(path.join(ROOT, 'package.json'));
+const templatePath = path.join(ROOT, 'packages', 'template', 'package.json');
+
+let pkgJson;
+if (fs.existsSync(templatePath)) {
+  pkgJson = require(templatePath);
+} else {
+  // Fallback template if file doesn't exist yet
+  pkgJson = {
+    name: '@lloyal-labs/lloyal.node-PLATFORM',
+    version: '0.0.0',
+    description: 'Lloyal native binary for PLATFORM',
+    main: 'index.js',
+    files: ['bin/', 'index.js'],
+    repository: {
+      type: 'git',
+      url: 'git+https://github.com/lloyal-ai/lloyal.node.git'
+    },
+    license: 'Apache-2.0'
+  };
+}
+
+// Update with actual values
+pkgJson.name = `@lloyal-labs/lloyal.node-${packageName}`;
+pkgJson.version = mainPackageJson.version;
+pkgJson.description = `Lloyal native binary for ${packageName}`;
+pkgJson.os = [osName];
+pkgJson.cpu = [arch];
+
+fs.writeFileSync(
+  path.join(PKG_DIR, 'package.json'),
+  JSON.stringify(pkgJson, null, 2) + '\n'
+);
+console.log(`  ✓ Created package.json`);
+
+// Create index.js
+console.log('\nGenerating index.js...');
+const indexJs = `// Platform-specific binary package for ${packageName}
+// This file resolves to the native binary in bin/
+
+const path = require('path');
+
+module.exports = path.join(__dirname, 'bin', 'lloyal.node');
+`;
+
+fs.writeFileSync(path.join(PKG_DIR, 'index.js'), indexJs);
+console.log(`  ✓ Created index.js`);
+
+// Summary
+console.log(`\n✅ Platform package created successfully!`);
+console.log(`\nPackage: @lloyal-labs/lloyal.node-${packageName}@${pkgJson.version}`);
+console.log(`Location: ${PKG_DIR}`);
+console.log(`\nContents:`);
+fs.readdirSync(BIN_DIR).forEach(f => {
+  const stats = fs.statSync(path.join(BIN_DIR, f));
+  const sizeMB = (stats.size / 1024 / 1024).toFixed(2);
+  console.log(`  - bin/${f} (${sizeMB} MB)`);
+});

package/scripts/download-test-models.sh

@@ -0,0 +1,30 @@
+#!/bin/bash
+set -e
+
+echo "Downloading test models..."
+
+mkdir -p models
+cd models
+
+# SmolLM2 1.7B Instruct Q4_K_M (1.0GB)
+if [ ! -f "SmolLM2-1.7B-Instruct-Q4_K_M.gguf" ]; then
+  echo "  → Downloading SmolLM2-1.7B-Instruct-Q4_K_M.gguf..."
+  curl -L -o "SmolLM2-1.7B-Instruct-Q4_K_M.gguf" \
+    "https://huggingface.co/HuggingFaceTB/SmolLM2-1.7B-Instruct-GGUF/resolve/main/smollm2-1.7b-instruct-q4_k_m.gguf"
+  echo "  ✓ Downloaded SmolLM2"
+else
+  echo "  ✓ SmolLM2 already exists"
+fi
+
+# Nomic Embed Text v1.5 Q4_K_M (80MB)
+if [ ! -f "nomic-embed-text-v1.5.Q4_K_M.gguf" ]; then
+  echo "  → Downloading nomic-embed-text-v1.5.Q4_K_M.gguf..."
+  curl -L -o "nomic-embed-text-v1.5.Q4_K_M.gguf" \
+    "https://huggingface.co/nomic-ai/nomic-embed-text-v1.5-GGUF/resolve/main/nomic-embed-text-v1.5.Q4_K_M.gguf"
+  echo "  ✓ Downloaded nomic-embed-text"
+else
+  echo "  ✓ nomic-embed-text already exists"
+fi
+
+echo ""
+echo "✅ All test models ready"

package/scripts/init-submodules.js

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+/**
+ * Initialize git submodules during npm install
+ *
+ * This is necessary because npm doesn't automatically initialize submodules
+ * when installing from GitHub URLs. Without this, llama.cpp/ and liblloyal/
+ * won't exist, causing build failures.
+ */
+
+const { execSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+const ROOT = path.join(__dirname, '..');
+
+console.log('[init-submodules] Checking for git submodules...');
+
+// Check if we're in a git repository
+const isGitRepo = fs.existsSync(path.join(ROOT, '.git'));
+
+if (!isGitRepo) {
+  console.log('[init-submodules] Not a git repository, skipping submodule initialization');
+  process.exit(0);
+}
+
+// Check if submodules are already initialized
+const llamaCppExists = fs.existsSync(path.join(ROOT, 'llama.cpp/.git'));
+const libloyalExists = fs.existsSync(path.join(ROOT, 'liblloyal/.git'));
+
+if (llamaCppExists && libloyalExists) {
+  console.log('[init-submodules] ✓ Submodules already initialized');
+  process.exit(0);
+}
+
+// Initialize submodules
+console.log('[init-submodules] Initializing git submodules...');
+try {
+  execSync('git submodule update --init --recursive', {
+    cwd: ROOT,
+    stdio: 'inherit'
+  });
+  console.log('[init-submodules] ✓ Submodules initialized successfully');
+} catch (error) {
+  console.error('[init-submodules] Failed to initialize submodules:', error.message);
+  console.error('[init-submodules] Please run manually: git submodule update --init --recursive');
+  process.exit(1);
+}

package/scripts/install.js

@@ -0,0 +1,138 @@
+#!/usr/bin/env node
+/**
+ * Smart installer for lloyal.node
+ *
+ * Strategy:
+ * 1. Check if prebuilt binary exists for this platform
+ * 2. If yes, copy to build/Release/ and exit
+ * 3. If no, show helpful error with build-from-source instructions
+ *
+ * Respects LLOYAL_GPU environment variable for GPU variant selection
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const PLATFORM = process.platform;
+const ARCH = process.arch;
+const ROOT = __dirname + '/..';
+const BUILD_DIR = path.join(ROOT, 'build', 'Release');
+
+// Logging helpers
+const log = (msg) => console.log(`[lloyal.node] ${msg}`);
+const error = (msg) => console.error(`[lloyal.node] ❌ ${msg}`);
+
+/**
+ * Check if a platform package is installed and has binaries
+ */
+function findPrebuilt(packageName) {
+  try {
+    const pkgPath = require.resolve(packageName);
+    const binPath = require(packageName); // index.js exports path to binary
+
+    if (fs.existsSync(binPath)) {
+      const binDir = path.dirname(binPath);
+      return binDir;
+    }
+  } catch (e) {
+    // Package not installed or doesn't export binary path
+  }
+  return null;
+}
+
+/**
+ * Copy prebuilt binaries to build/Release/
+ */
+function installPrebuilt(binDir, packageName) {
+  log(`Found prebuilt binaries in ${packageName}`);
+
+  try {
+    // Create build/Release directory
+    fs.mkdirSync(BUILD_DIR, { recursive: true });
+
+    // Copy all files from bin directory
+    const files = fs.readdirSync(binDir);
+    files.forEach(file => {
+      const src = path.join(binDir, file);
+      const dest = path.join(BUILD_DIR, file);
+
+      if (fs.statSync(src).isFile()) {
+        fs.copyFileSync(src, dest);
+        log(`  ✓ Copied ${file}`);
+      }
+    });
+
+    log(`✅ Installed prebuilt binaries successfully`);
+    process.exit(0);
+  } catch (e) {
+    error(`Failed to install prebuilt: ${e.message}`);
+    // Don't exit - fall through to source build
+  }
+}
+
+/**
+ * Main installation logic
+ */
+function main() {
+  log(`Platform: ${PLATFORM}-${ARCH}`);
+
+  // 1. Check for user-specified GPU variant via environment variable
+  if (process.env.LLOYAL_GPU) {
+    const gpu = process.env.LLOYAL_GPU.toLowerCase();
+    const packageName = `@lloyal-labs/lloyal.node-${PLATFORM}-${ARCH}-${gpu}`;
+
+    log(`LLOYAL_GPU=${gpu}, looking for ${packageName}...`);
+    const binDir = findPrebuilt(packageName);
+
+    if (binDir) {
+      installPrebuilt(binDir, packageName);
+      return; // exit(0) called in installPrebuilt
+    } else {
+      log(`  ⚠️  Package ${packageName} not found`);
+    }
+  }
+
+  // 2. Check for GPU variants in priority order
+  const gpuVariants = ['cuda', 'vulkan'];
+  for (const gpu of gpuVariants) {
+    const packageName = `@lloyal-labs/lloyal.node-${PLATFORM}-${ARCH}-${gpu}`;
+    const binDir = findPrebuilt(packageName);
+
+    if (binDir) {
+      log(`Auto-detected GPU variant: ${gpu}`);
+      installPrebuilt(binDir, packageName);
+      return; // exit(0) called in installPrebuilt
+    }
+  }
+
+  // 3. Check for default platform package (CPU or Metal on macOS)
+  const defaultPackage = `@lloyal-labs/lloyal.node-${PLATFORM}-${ARCH}`;
+  const binDir = findPrebuilt(defaultPackage);
+
+  if (binDir) {
+    installPrebuilt(binDir, defaultPackage);
+    return; // exit(0) called in installPrebuilt
+  }
+
+  // 4. No prebuilt found - error with helpful message
+  log('');
+  error('No prebuilt binary found for your platform');
+  log('');
+  log(`  Platform: ${PLATFORM}-${ARCH}`);
+  log('');
+  log('  Options:');
+  log('  1. Install a platform-specific package:');
+  log(`     npm install @lloyal-labs/lloyal.node-${PLATFORM}-${ARCH}`);
+  log('');
+  log('  2. Build from source (requires C++20, CMake 3.18+):');
+  log('     git clone --recursive https://github.com/lloyal-ai/lloyal.node.git');
+  log('     cd lloyal.node && npm run build');
+  log('');
+  log('  See: https://github.com/lloyal-ai/lloyal.node#building');
+  log('');
+  
+  process.exit(1);
+}
+
+// Run installer
+main();

package/scripts/sync-versions.js

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+/**
+ * Synchronize all platform package versions with main package version
+ *
+ * Ensures optionalDependencies in package.json all reference the current version
+ * Run before publishing or after `npm version`
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const ROOT = path.join(__dirname, '..');
+const PKG_JSON_PATH = path.join(ROOT, 'package.json');
+
+console.log('[sync-versions] Synchronizing package versions...\n');
+
+// Read main package.json
+const pkg = JSON.parse(fs.readFileSync(PKG_JSON_PATH, 'utf8'));
+const version = pkg.version;
+
+console.log(`Main package version: ${version}`);
+
+// Update optionalDependencies
+if (pkg.optionalDependencies) {
+  console.log('\nUpdating optionalDependencies:');
+
+  Object.keys(pkg.optionalDependencies).forEach(dep => {
+    const oldVersion = pkg.optionalDependencies[dep];
+    pkg.optionalDependencies[dep] = version;
+
+    if (oldVersion !== version) {
+      console.log(`  ${dep}: ${oldVersion} → ${version}`);
+    } else {
+      console.log(`  ${dep}: ${version} (unchanged)`);
+    }
+  });
+
+  // Write updated package.json
+  fs.writeFileSync(PKG_JSON_PATH, JSON.stringify(pkg, null, 2) + '\n');
+  console.log('\n✅ package.json updated');
+} else {
+  console.log('\n⚠️  No optionalDependencies found in package.json');
+}
+
+// Update any existing platform packages in packages/ directory
+const PACKAGES_DIR = path.join(ROOT, 'packages');
+
+if (fs.existsSync(PACKAGES_DIR)) {
+  const dirs = fs.readdirSync(PACKAGES_DIR).filter(f => {
+    const stat = fs.statSync(path.join(PACKAGES_DIR, f));
+    return stat.isDirectory() && f !== 'template';
+  });
+
+  if (dirs.length > 0) {
+    console.log('\nUpdating platform packages:');
+
+    dirs.forEach(dir => {
+      const pkgPath = path.join(PACKAGES_DIR, dir, 'package.json');
+
+      if (fs.existsSync(pkgPath)) {
+        const platformPkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+        const oldVersion = platformPkg.version;
+
+        platformPkg.version = version;
+        fs.writeFileSync(pkgPath, JSON.stringify(platformPkg, null, 2) + '\n');
+
+        if (oldVersion !== version) {
+          console.log(`  ${platformPkg.name}: ${oldVersion} → ${version}`);
+        } else {
+          console.log(`  ${platformPkg.name}: ${version} (unchanged)`);
+        }
+      }
+    });
+
+    console.log('\n✅ Platform packages updated');
+  }
+}
+
+console.log('\n✅ Version synchronization complete!');