feat: support prebuilt VPP packages (runtime-v4 upload + arduino-cli mixed compile/link)

src/backend/editor/compiler/__tests__/handle-core-installation.test.ts

@@ -0,0 +1,128 @@
+import { spawn } from 'node:child_process'
+import { EventEmitter } from 'node:events'
+
+import { CompilerModule } from '../compiler-module'
+
+// Electron is imported transitively by compiler-module; stub the bits the
+// instantiation path actually touches so jest doesn't load the real runtime.
+jest.mock('electron', () => ({
+  app: {
+    getPath: jest.fn().mockReturnValue('/tmp/mock-user-data'),
+    getAppPath: jest.fn().mockReturnValue('/tmp/mock-app-root'),
+    isPackaged: false,
+    getVersion: jest.fn().mockReturnValue('0.0.0-test'),
+  },
+  dialog: { showSaveDialog: jest.fn().mockResolvedValue({ filePath: '/tmp/mock-save-path' }) },
+}))
+jest.mock('electron/main', () => ({}), { virtual: true })
+
+// compiler-module pulls in recipe-exec, which calls promisify(execFile) at
+// module load, so the mock must expose exec/execFile (with promisify.custom)
+// alongside spawn. handleCoreInstallation reaches spawn only on the install
+// path (core absent OR a pinned version is requested); the skip-path tests
+// assert spawn is NOT called.
+jest.mock('node:child_process', () => {
+  const { promisify } = jest.requireActual('node:util') as typeof import('node:util')
+  const noop = async () => ({ stdout: '', stderr: '' })
+  const exec = (
+    _cmd: string,
+    _opts: unknown,
+    cb: (err: Error | null, val?: { stdout: string; stderr: string }) => void,
+  ) => {
+    noop().then((v) => cb(null, v))
+    return { kill: () => undefined }
+  }
+  ;(exec as unknown as { [k: symbol]: unknown })[promisify.custom] = () => noop()
+  const execFile = (
+    _command: string,
+    _args: ReadonlyArray<string>,
+    _opts: unknown,
+    cb: (err: Error | null, val?: { stdout: string; stderr: string }) => void,
+  ) => {
+    noop().then((v) => cb(null, v))
+    return { kill: () => undefined }
+  }
+  ;(execFile as unknown as { [k: symbol]: unknown })[promisify.custom] = () => noop()
+  return { exec, execFile, spawn: jest.fn() }
+})
+;(process as unknown as { resourcesPath: string }).resourcesPath ??= process.cwd()
+
+type InstalledCores = Awaited<ReturnType<CompilerModule['getArduinoInstalledCores']>>
+
+// A fake ChildProcess that satisfies handleCoreInstallation's wiring
+// (stdout/stderr `.on`, plus a `close` event) and reports the given exit code
+// on the next tick so the `.on('close')` handler is registered first.
+function fakeChild(exitCode = 0) {
+  const child = new EventEmitter() as EventEmitter & { stdout: EventEmitter; stderr: EventEmitter }
+  child.stdout = new EventEmitter()
+  child.stderr = new EventEmitter()
+  setImmediate(() => child.emit('close', exitCode))
+  return child
+}
+
+describe('handleCoreInstallation (prebuilt core pin = exact manifest version)', () => {
+  let compilerModule: CompilerModule
+
+  beforeEach(() => {
+    compilerModule = new CompilerModule()
+    jest.mocked(spawn).mockReset()
+  })
+
+  it('does nothing when boardCore is null', async () => {
+    const log = jest.fn()
+    const coresSpy = jest.spyOn(compilerModule, 'getArduinoInstalledCores')
+    await compilerModule.handleCoreInstallation(null, log)
+    expect(coresSpy).not.toHaveBeenCalled()
+    expect(spawn).not.toHaveBeenCalled()
+    expect(log).not.toHaveBeenCalled()
+  })
+
+  it('installs the EXACT pinned version even when a different version is already present', async () => {
+    const log = jest.fn()
+    jest.mocked(spawn).mockReturnValue(fakeChild(0) as unknown as ReturnType<typeof spawn>)
+    jest
+      .spyOn(compilerModule, 'getArduinoInstalledCores')
+      .mockResolvedValue({ 'FACTS:samd': { version: '1.7.99' } } as unknown as InstalledCores)
+
+    await compilerModule.handleCoreInstallation('FACTS:samd', log, '1.7.13')
+
+    expect(spawn).toHaveBeenCalledTimes(1)
+    const [, argv] = jest.mocked(spawn).mock.calls[0]
+    expect(argv).toEqual(expect.arrayContaining(['core', 'install', 'FACTS:samd@1.7.13']))
+  })
+
+  it('installs the pinned version when the core is absent', async () => {
+    const log = jest.fn()
+    jest.mocked(spawn).mockReturnValue(fakeChild(0) as unknown as ReturnType<typeof spawn>)
+    jest.spyOn(compilerModule, 'getArduinoInstalledCores').mockResolvedValue({} as InstalledCores)
+
+    await compilerModule.handleCoreInstallation('FACTS:samd', log, '1.7.13')
+
+    expect(spawn).toHaveBeenCalledTimes(1)
+    const [, argv] = jest.mocked(spawn).mock.calls[0]
+    expect(argv).toEqual(expect.arrayContaining(['core', 'install', 'FACTS:samd@1.7.13']))
+  })
+
+  it('rejects when the pinned version install fails (non-zero exit)', async () => {
+    const log = jest.fn()
+    jest.mocked(spawn).mockReturnValue(fakeChild(1) as unknown as ReturnType<typeof spawn>)
+    jest.spyOn(compilerModule, 'getArduinoInstalledCores').mockResolvedValue({} as InstalledCores)
+
+    await expect(compilerModule.handleCoreInstallation('FACTS:samd', log, '9.9.9')).rejects.toThrow(
+      /exited with code 1/,
+    )
+  })
+
+  it('skips install (no spawn) only when the core is present AND no version is pinned', async () => {
+    const log = jest.fn()
+    jest
+      .spyOn(compilerModule, 'getArduinoInstalledCores')
+      .mockResolvedValue({ 'arduino:avr': { version: '1.8.6' } } as unknown as InstalledCores)
+
+    await compilerModule.handleCoreInstallation('arduino:avr', log)
+
+    expect(spawn).not.toHaveBeenCalled()
+    const message = log.mock.calls.map((c) => String(c[0])).join('\n')
+    expect(message).toMatch(/already installed/)
+  })
+})

src/backend/editor/compiler/__tests__/handle-vendor-plugin-packaging.test.ts

@@ -0,0 +1,159 @@
+/**
+ * `CompilerModule.handleVendorPluginPackaging` — prebuilt vs source
+ * provisioning branch.
+ *
+ * The packager treats `hal.pluginEntry` differently depending on
+ * `hal.provisioning`:
+ *   - "prebuilt": pluginEntry IS the directory holding the precompiled
+ *     `.o` objects + link-only Makefile — copied verbatim.
+ *   - source (default / absent): pluginEntry is the entry source FILE,
+ *     so the directory to copy is its parent.
+ *
+ * We drive the real method against a temp filesystem, mocking only the
+ * package manager (which board/manifest it sees) and electron (so the
+ * module import doesn't try to reach the Electron app at load time).
+ * The method doesn't touch `this`, so we invoke it via the prototype
+ * and skip the constructor entirely.
+ */
+
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'fs'
+import { tmpdir } from 'os'
+import { join } from 'path'
+
+// The module calls `electronApp.getPath(...)` in its constructor; we never
+// construct it here, but the top-level `import electron` still has to resolve.
+jest.mock('electron', () => ({
+  app: { getPath: () => tmpdir() },
+  dialog: {},
+  MessageChannelMain: class {},
+}))
+
+const listInstalled = jest.fn()
+const getInstalledPackageManifest = jest.fn()
+jest.mock('../../package-manager', () => ({
+  PackageManagerModule: jest.fn().mockImplementation(() => ({
+    listInstalled,
+    getInstalledPackageManifest,
+  })),
+}))
+
+// eslint-disable-next-line import/first
+import { CompilerModule } from '../compiler-module'
+
+type LogEntry = { message: string; level: string }
+
+const BOARD = 'Raspberry Pi (prebuilt test)'
+
+const handler = CompilerModule.prototype.handleVendorPluginPackaging
+
+function makeManifest(hal: Record<string, unknown>) {
+  return {
+    devices: [
+      {
+        name: BOARD,
+        target: { type: 'runtime-v4' },
+        hal,
+        moduleSystem: undefined,
+      },
+    ],
+  }
+}
+
+/** Writes a plugin directory with two payload files + an excluded one. */
+function writePluginDir(pkgDir: string): string {
+  const pluginDir = join(pkgDir, 'hal', 'runtime-v4', 'plugin')
+  mkdirSync(pluginDir, { recursive: true })
+  writeFileSync(join(pluginDir, 'rpi_plugin.o'), 'OBJECT-BYTES')
+  writeFileSync(join(pluginDir, 'Makefile'), 'all:\n\techo link\n')
+  // Excluded by the packager — must not be copied into vpp_plugin/.
+  writeFileSync(join(pluginDir, 'config_template.json'), JSON.stringify({ plugin_name: 'rpi_gpio', pins: [] }))
+  return pluginDir
+}
+
+describe('handleVendorPluginPackaging — provisioning branch', () => {
+  let pkgDir: string
+  let projectDir: string
+  let targetDir: string
+  let logs: LogEntry[]
+
+  const runFor = (hal: Record<string, unknown>) => {
+    listInstalled.mockReturnValue([{ packageId: 'com.openplc.rpi', path: pkgDir }])
+    getInstalledPackageManifest.mockReturnValue(makeManifest(hal))
+    return handler.call(
+      {} as CompilerModule,
+      BOARD,
+      projectDir,
+      targetDir,
+      (message: string | Buffer, level?: string) => {
+        logs.push({ message: String(message), level: level ?? '' })
+      },
+    )
+  }
+
+  beforeEach(() => {
+    jest.clearAllMocks()
+    pkgDir = mkdtempSync(join(tmpdir(), 'vpp-pkg-'))
+    projectDir = mkdtempSync(join(tmpdir(), 'vpp-proj-'))
+    targetDir = mkdtempSync(join(tmpdir(), 'vpp-target-'))
+    logs = []
+    writePluginDir(pkgDir)
+  })
+
+  afterEach(() => {
+    for (const dir of [pkgDir, projectDir, targetDir]) {
+      rmSync(dir, { recursive: true, force: true })
+    }
+  })
+
+  it('treats pluginEntry as a directory when provisioning is "prebuilt"', async () => {
+    await runFor({
+      type: 'runtime-v4-plugin',
+      pluginType: 'native',
+      provisioning: 'prebuilt',
+      pluginEntry: 'hal/runtime-v4/plugin',
+      configTemplate: 'hal/runtime-v4/plugin/config_template.json',
+    })
+
+    const dest = join(targetDir, 'vpp_plugin')
+    expect(existsSync(join(dest, 'rpi_plugin.o'))).toBe(true)
+    expect(existsSync(join(dest, 'Makefile'))).toBe(true)
+    // Excluded file is never copied.
+    expect(existsSync(join(dest, 'config_template.json'))).toBe(false)
+    // Deterministic integrity checksum is emitted.
+    expect(existsSync(join(dest, 'checksum.sha256'))).toBe(true)
+    // The summary log distinguishes the prebuilt path.
+    expect(logs.some((l) => /prebuilt file\(s\)/.test(l.message))).toBe(true)
+  })
+
+  it('treats pluginEntry as a file and copies its parent dir in source mode (provisioning absent)', async () => {
+    // Source-mode pluginEntry points at the entry FILE; the directory to copy
+    // is its parent — the same plugin dir, reached via dirname().
+    writeFileSync(join(pkgDir, 'hal', 'runtime-v4', 'plugin', 'rpi_plugin.c'), 'int main(){}')
+
+    await runFor({
+      type: 'runtime-v4-plugin',
+      pluginType: 'native',
+      pluginEntry: 'hal/runtime-v4/plugin/rpi_plugin.c',
+      configTemplate: 'hal/runtime-v4/plugin/config_template.json',
+    })
+
+    const dest = join(targetDir, 'vpp_plugin')
+    expect(existsSync(join(dest, 'rpi_plugin.c'))).toBe(true)
+    expect(existsSync(join(dest, 'Makefile'))).toBe(true)
+    expect(existsSync(join(dest, 'config_template.json'))).toBe(false)
+    expect(logs.some((l) => /source file\(s\)/.test(l.message))).toBe(true)
+  })
+
+  it('copies the payload byte-for-byte (prebuilt object content preserved)', async () => {
+    await runFor({
+      type: 'runtime-v4-plugin',
+      pluginType: 'native',
+      provisioning: 'prebuilt',
+      pluginEntry: 'hal/runtime-v4/plugin',
+      configTemplate: 'hal/runtime-v4/plugin/config_template.json',
+    })
+
+    const copied = readFileSync(join(targetDir, 'vpp_plugin', 'rpi_plugin.o'), 'utf-8')
+    expect(copied).toBe('OBJECT-BYTES')
+  })
+})

src/backend/editor/compiler/compiler-module.ts

@@ -1036,23 +1036,34 @@ class CompilerModule {
   async handleCoreInstallation(
     boardCore: string | null,
     handleOutputData: (chunk: Buffer | string, logLevel?: 'info' | 'error') => void,
+    coreVersion?: string,
   ) {
     if (boardCore === null) return
 
     const isCoreInstalled = Object.keys(await this.getArduinoInstalledCores()).some((core) => core === boardCore)
-    if (isCoreInstalled) {
+    // Without a pinned version, any installed version is fine — skip the install.
+    // With a pinned version (prebuilt arduino libraries are ABI-locked to it),
+    // always run `core install <id>@<version>`: arduino-cli installs exactly that
+    // version and fails if it does not exist, pinning the core to the version
+    // the precompiled library was built against.
+    if (!coreVersion && isCoreInstalled) {
       handleOutputData(`Core ${boardCore} is already installed.`, 'info')
       return
     }
 
+    const coreRef = coreVersion ? `${boardCore}@${coreVersion}` : boardCore
+    if (coreVersion) {
+      handleOutputData(`Installing pinned core ${coreRef} (required by a prebuilt library)...`, 'info')
+    }
+
     let binaryPath = this.arduinoCliBinaryPath
 
     if (CompilerModule.HOST_PLATFORM === 'win32') {
       // INFO: On Windows, we need to add the .exe extension to the binary path.
       binaryPath += '.exe'
     }
     return new Promise<MethodsResult<string | Buffer>>((resolve, reject) => {
-      const executeCommand = spawn(binaryPath, ['core', 'install', boardCore, ...this.arduinoCliBaseParameters])
+      const executeCommand = spawn(binaryPath, ['core', 'install', coreRef, ...this.arduinoCliBaseParameters])
 
       let stderrData = ''
 
@@ -1790,6 +1801,13 @@ class CompilerModule {
       ...cxxFlagsArg,
       '--library',
       precompiledLibDir,
+      // Prebuilt arduino-hal (mixed): the vendor's precompiled library. The
+      // open hal.source layer (renamed to arduino.cpp, compiled here alongside
+      // the sketch — NOT in the precompile pass) does `#include "p1am_vendor.h"`,
+      // so arduino-cli needs the lib's src/ on the include path. Passing it as a
+      // 2nd --library both resolves the boundary header and auto-links the
+      // src/<build.mcu>/lib*.a archive (the lib ships precompiled=full).
+      ...(info.precompiledLibraryDir ? ['--library', info.precompiledLibraryDir] : []),
       '--build-property',
       `compiler.libraries.ldflags=-L${precompiledArchDir} -lOpenPLCUserLib`,
       ...this.arduinoCliBaseParameters,
@@ -2243,19 +2261,24 @@ class CompilerModule {
         handleOutputData('VPP board has no HAL configTemplate, skipping plugin config generation', 'info')
       }
 
-      // --- Step 2: Copy plugin source + generate checksum ---
+      // --- Step 2: Copy plugin payload + generate checksum ---
       const pluginEntryRelPath = matchingDevice.hal?.pluginEntry
       if (!pluginEntryRelPath) {
         handleOutputData('VPP board has no HAL pluginEntry, skipping plugin source upload', 'info')
         return
       }
 
-      // The plugin source directory is the parent directory of pluginEntry.
+      // Resolve the plugin directory. In "source" mode (default) pluginEntry is
+      // the entry source file, so the dir is its parent. In "prebuilt" mode
+      // (provisioning === 'prebuilt') pluginEntry is the directory itself,
+      // holding the precompiled .o objects plus the link-only Makefile.
       // pluginEntryRelPath is supplied by the package manifest; without
       // containment, an entry like `../../../etc` would resolve outside
       // matchingPackagePath and the recursive-copy below would slurp
       // arbitrary host files into the build's vpp_plugin directory.
-      const pluginSourceDir = join(matchingPackagePath, path.dirname(pluginEntryRelPath))
+      const isPrebuilt = matchingDevice.hal?.provisioning === 'prebuilt'
+      const pluginDirRelPath = isPrebuilt ? pluginEntryRelPath : path.dirname(pluginEntryRelPath)
+      const pluginSourceDir = join(matchingPackagePath, pluginDirRelPath)
       try {
         assertPathContained(matchingPackagePath, pluginSourceDir, 'matchingDevice.hal.pluginEntry')
       } catch (err) {
@@ -2346,7 +2369,7 @@ class CompilerModule {
       await writeFile(join(destPluginDir, 'checksum.sha256'), combinedHash + '\n', 'utf-8')
 
       handleOutputData(
-        `Copied ${copiedFiles.length} VPP plugin source file(s) to vpp_plugin/ (checksum: ${combinedHash.slice(0, 12)}...)`,
+        `Copied ${copiedFiles.length} VPP plugin ${isPrebuilt ? 'prebuilt' : 'source'} file(s) to vpp_plugin/ (checksum: ${combinedHash.slice(0, 12)}...)`,
         'info',
       )
     } catch (error) {

src/backend/editor/compiler/editor-compiler-platform-port.ts

@@ -239,10 +239,14 @@ export function createEditorCompilerPlatformPort(
      */
     async installArduinoCore(args: InstallArduinoCoreArgs, log: PlatformLog): Promise<UploadResult> {
       try {
-        await handlers.handleCoreInstallation(args.coreId, (chunk, level) => {
-          const message = typeof chunk === 'string' ? chunk : chunk.toString()
-          log(message, level ?? 'info')
-        })
+        await handlers.handleCoreInstallation(
+          args.coreId,
+          (chunk, level) => {
+            const message = typeof chunk === 'string' ? chunk : chunk.toString()
+            log(message, level ?? 'info')
+          },
+          args.coreVersion,
+        )
         return { ok: true }
       } catch (error) {
         const message = error instanceof Error ? error.message : String(error)