nodalis-compiler 1.0.21 → 1.0.23

package/CHANGELOG.md

@@ -1,9 +1,11 @@
 # Changelog
 
-## [1.0.21] 2026-03-03
+## [1.0.23] 2026-03-03
 - Changed IEC parser to interpret Function Blocks that are actually standard functions to a formal function call.
 - Fixed nodejs/jint compiles to put executables in a bin folder.
 - Fixed syntax errors with repeat.
+- Prevent stale files in ST bundle compile.
+- Added a new "action" for "get-toolchains", which will download the necessary toolchains for CPP and Arduino.
 
 ## [1.0.17] 2026-02-25
 - Added support for compilation of multiple ST files as a single project.

package/README.md

@@ -56,6 +56,7 @@ Usage:
 Actions:
   --action list-compilers
   --action compile
+  --action get-toolchains
 ```
 
 ---
@@ -68,6 +69,18 @@ Actions:
 nodalis --action list-compilers
 ```
 
+### ✔ Install managed C/C++ toolchains
+
+```bash
+nodalis --action get-toolchains
+```
+
+This installs:
+- Managed Zig-based C/C++ cross-compilers
+- Managed `arduino-cli`
+- Default Arduino board cores for the built-in Nodalis FQBN targets
+- Required Arduino libraries for the built-in Nodalis Arduino runtime, including `ArduinoModbus`
+
 ---
 
 ### ✔ Compile a Structured Text program
@@ -113,23 +126,34 @@ await app.compile({
 
 #### Dependencies
 
-- Uses a default cross-compiler profile tuned for macOS-style Clang/LLVM toolchains when no overrides are provided.
+- Uses managed Zig-based toolchain wrappers under `~/.nodalis/toolchains` when no overrides are provided.
+- Install those toolchains with `nodalis --action get-toolchains`.
+- `get-toolchains` also installs a managed `arduino-cli` plus the default Nodalis Arduino board cores.
+- `get-toolchains` also installs the default Arduino libraries required by the built-in runtime support.
+- On Windows hosts, the managed toolchain installs wrappers for all Linux and Windows targets.
+- On macOS hosts, the managed toolchain installs wrappers for all Linux, Windows, and macOS targets.
 - Supply a `toolchain.json` file beside your source to describe a custom toolchain. Example:
 
 ```json
 {
-    "linux-arm": "arm-linux-gnueabi-g++",
-    "linux-arm64": "aarch64-linux-gnu-g++",
-    "linux-x64": "x86_64-linux-gnu-g++",
-    "macos-arm64": "clang++",
-    "macos-x64": "clang++",
-    "windows-x64": "x86_64-w64-mingw32-g++",
-    "windows-arm64": "/opt/llvm-mingw/bin/aarch64-w64-mingw32-g++"
+    "linux-arm": "/Users/you/.nodalis/toolchains/zig/0.15.2/wrappers/zig-linux-arm-c++",
+    "linux-arm64": "/Users/you/.nodalis/toolchains/zig/0.15.2/wrappers/zig-linux-arm64-c++",
+    "linux-x64": "/Users/you/.nodalis/toolchains/zig/0.15.2/wrappers/zig-linux-x64-c++",
+    "windows-x64": "/Users/you/.nodalis/toolchains/zig/0.15.2/wrappers/zig-windows-x64-c++",
+    "windows-arm64": "/Users/you/.nodalis/toolchains/zig/0.15.2/wrappers/zig-windows-arm64-c++",
+    "macos-x64": "/Users/you/.nodalis/toolchains/zig/0.15.2/wrappers/zig-macos-x64-c++",
+    "macos-arm64": "/Users/you/.nodalis/toolchains/zig/0.15.2/wrappers/zig-macos-arm64-c++"
 }
 ```
 
-- Without an explicit file Nodalis falls back to the default compiler for the host OS (`clang++` on macOS, `g++` on Linux, and `cl.exe` or MinGW-w64 `g++` on Windows).
-- Common cross-compiler sources: Homebrew packages (`brew install armmbed/formulae/arm-none-eabi-gcc`) and osxcross for macOS targeting, MinGW-w64/MSYS2 or Visual Studio Build Tools for Windows, and distro packages such as `gcc-arm-linux-gnueabihf` or `x86_64-w64-mingw32-g++` on Linux.
+- The managed installer skips macOS targets on non-macOS hosts.
+- `toolchain.json` remains the escape hatch for unsupported or custom compiler setups.
+
+### Arduino
+
+Nodalis uses a managed `arduino-cli` by default when present under `~/.nodalis/toolchains/arduino-cli`.
+Running `nodalis --action get-toolchains` also installs the default board cores required by the built-in Arduino FQBN targets, currently including `arduino:mbed_opta:opta`.
+It also installs the default Arduino libraries required by the shipped support code, currently including `ArduinoModbus`.
 
 #### Variations
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nodalis-compiler",
-  "version": "1.0.21",
+  "version": "1.0.23",
   "description": "Compiles IEC-61131-3/10 languages into code that can be used as a PLC on multiple platforms.",
   "icon": "nodalis.png",
   "main": "src/nodalis.js",

package/src/compilers/ArduinoCompiler.js

@@ -23,14 +23,12 @@ import { Compiler, IECLanguage, OutputType, CommunicationProtocol } from './Comp
 import * as iec from './iec-parser/parser.js';
 import { parseStructuredText } from './st-parser/parser.js';
 import { transpile } from './st-parser/gcctranspiler.js';
+import { DEFAULT_ARDUINO_FQBN } from './arduinoDefaults.js';
+import { getManagedArduinoCliPath, getManagedArduinoCliExecOptions } from '../toolchains.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 
-const DEFAULT_ARDUINO_FQBN = {
-    'arduino-opta': 'arduino:mbed_opta:opta'
-};
-
 const MODBUS_ARDUINO_CORE_IDS = new Set([
     'arduino:megaavr',
     'arduino:samd',
@@ -115,6 +113,7 @@ export class ArduinoCompiler extends Compiler {
         let sourceCode = '';
         let bundleEntryProgram = '';
         if (directoryBundleMode) {
+            this.cleanupStructuredTextBundleArtifacts(sourcePath);
             const { combinedSource, entryProgramName } = this.loadStructuredTextBundle(sourcePath, resourceName);
             sourceCode = combinedSource;
             bundleEntryProgram = entryProgramName;
@@ -256,7 +255,7 @@ void loop() {
         fs.cpSync(path.join(supportDir, 'json.hpp'), path.join(outputPath, 'json.hpp'), { force: true });
 
         if (this.isExecutableOutput()) {
-            const arduinoCli = compilerConfig.arduino_cli || compilerConfig.arduinoCli || 'arduino-cli';
+            const arduinoCli = compilerConfig.arduino_cli || compilerConfig.arduinoCli || getManagedArduinoCliPath();
             const arduinoFqbn = this.resolveArduinoFqbn(target, compilerConfig);
             if (!arduinoFqbn) {
                 throw new Error(`No Arduino FQBN configured for target "${target}". Use an explicit FQBN target (e.g. arduino:mbed_opta:opta) or add "arduino_fqbn" to toolchain.json.`);
@@ -271,23 +270,25 @@ void loop() {
             fs.mkdirSync(binDir, { recursive: true });
             const arduinoCompileCmd = `${arduinoCli} compile --fqbn "${arduinoFqbn}" "${outputPath}" --build-path "${buildDir}" --output-dir "${binDir}" --export-binaries`;
             try {
-                execSync(arduinoCompileCmd, { stdio: 'pipe' });
+                execSync(arduinoCompileCmd, getManagedArduinoCliExecOptions({ stdio: 'pipe' }));
             } catch (err) {
                 const stderrText = getExecOutputText(err?.stderr);
                 const stdoutText = getExecOutputText(err?.stdout);
                 const compilerOutput = [stderrText, stdoutText].filter(Boolean).join('\n');
+                const missingArduinoLibrary = compilerOutput.includes('ArduinoModbus.h') || compilerOutput.includes('No such file or directory');
                 const details = compilerOutput || err.message;
                 throw new Error(
-                    `Arduino CLI build failed for "${arduinoFqbn}". Verify arduino-cli and board core availability.\n${details}`
+                    `Arduino CLI build failed for "${arduinoFqbn}". ` +
+                    `${missingArduinoLibrary
+                        ? 'Run "nodalis --action get-toolchains" to install the managed Arduino cores and libraries.'
+                        : 'Verify arduino-cli, board core, and library availability.'}\n${details}`
                 );
             }
         }
     }
 
     loadStructuredTextBundle(sourcePath, resourceName) {
-        const stFiles = fs.readdirSync(sourcePath, { withFileTypes: true })
-            .filter((entry) => entry.isFile() && entry.name.toLowerCase().endsWith('.st'))
-            .map((entry) => entry.name);
+        const stFiles = this.listStructuredTextBundleFiles(sourcePath);
 
         if (stFiles.length === 0) {
             throw new Error(`No .st files found in source directory "${sourcePath}".`);
@@ -354,7 +355,7 @@ void loop() {
 
         let coreList = '';
         try {
-            coreList = execSync(`${arduinoCli} core list`, { encoding: 'utf8' });
+            coreList = execSync(`${arduinoCli} core list`, getManagedArduinoCliExecOptions({ encoding: 'utf8' }));
         } catch (err) {
             throw new Error(`Failed to query installed Arduino cores using "${arduinoCli}". ${err.message}`);
         }
@@ -363,8 +364,8 @@ void loop() {
         }
 
         try {
-            execSync(`${arduinoCli} core update-index`, { stdio: 'inherit' });
-            execSync(`${arduinoCli} core install ${coreId}`, { stdio: 'inherit' });
+            execSync(`${arduinoCli} core update-index`, getManagedArduinoCliExecOptions({ stdio: 'inherit' }));
+            execSync(`${arduinoCli} core install ${coreId}`, getManagedArduinoCliExecOptions({ stdio: 'inherit' }));
         } catch (err) {
             throw new Error(`Failed to install Arduino core "${coreId}" required for ${arduinoFqbn}. ${err.message}`);
         }
@@ -388,7 +389,10 @@ void loop() {
         const targets = Object.keys(DEFAULT_ARDUINO_FQBN);
 
         try {
-            const boardListRaw = execSync('arduino-cli board listall --format json', { encoding: 'utf8' });
+            const boardListRaw = execSync(
+                `${getManagedArduinoCliPath()} board listall --format json`,
+                getManagedArduinoCliExecOptions({ encoding: 'utf8' })
+            );
             const boardList = JSON.parse(boardListRaw);
             const boards = Array.isArray(boardList.boards) ? boardList.boards : [];
 

package/src/compilers/CPPCompiler.js

@@ -24,19 +24,12 @@ import { parseStructuredText } from './st-parser/parser.js';
 import { transpile } from './st-parser/gcctranspiler.js';
 import { fileURLToPath } from 'node:url';
 import { dirname } from 'node:path';
+import { getDefaultToolchain, getToolchainRoot, isManagedZigCompiler } from '../toolchains.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 
-const DEFAULT_TOOLCHAIN = {
-    "linux-arm": "arm-linux-gnueabi-g++",
-    "linux-arm64": "aarch64-linux-gnu-g++",
-    "linux-x64": "x86_64-linux-gnu-g++",
-    "macos-arm64": "clang++",
-    "macos-x64": "clang++",
-    "windows-x64": "x86_64-w64-mingw32-g++",
-    "windows-arm64": "/opt/llvm-mingw/bin/aarch64-w64-mingw32-g++"
-};
+const DEFAULT_TOOLCHAIN = getDefaultToolchain();
 
 let ToolChain = { ...DEFAULT_TOOLCHAIN };
 
@@ -79,7 +72,7 @@ export class CPPCompiler extends Compiler {
         const isStructuredTextLanguage = String(language || '').toUpperCase() === IECLanguage.STRUCTURED_TEXT;
         const directoryBundleMode = sourceIsDirectory && isStructuredTextLanguage && typeof resourceName === 'string' && resourceName.trim().length > 0;
 
-        ToolChain = { ...DEFAULT_TOOLCHAIN };
+        ToolChain = { ...getDefaultToolchain() };
         const sourceDir = sourceIsDirectory ? sourcePath : path.dirname(sourcePath);
         const toolchainConfigPath = path.join(sourceDir, "toolchain.json");
         if (fs.existsSync(toolchainConfigPath)) {
@@ -103,6 +96,7 @@ export class CPPCompiler extends Compiler {
         let bundleEntryProgram = '';
 
         if (directoryBundleMode) {
+            this.cleanupStructuredTextBundleArtifacts(sourcePath);
             const { combinedSource, entryProgramName } = this.loadStructuredTextBundle(sourcePath, resourceName);
             sourceCode = combinedSource;
             bundleEntryProgram = entryProgramName;
@@ -368,7 +362,12 @@ int main() {
                 .forEach((dir) => searchDirs.add(dir));
         }
 
-        const compilerPath = execSync(`which "${compiler}"`, { encoding: 'utf8' }).trim();
+        const compilerPath = path.isAbsolute(compiler)
+            ? compiler
+            : execSync(process.platform === 'win32' ? `where "${compiler}"` : `which "${compiler}"`, { encoding: 'utf8' })
+                .split(/\r?\n/)
+                .map((line) => line.trim())
+                .find(Boolean);
         if (compilerPath) {
             const compilerDir = path.dirname(compilerPath);
             searchDirs.add(compilerDir);
@@ -400,9 +399,7 @@ int main() {
     }
 
     loadStructuredTextBundle(sourcePath, resourceName) {
-        const stFiles = fs.readdirSync(sourcePath, { withFileTypes: true })
-            .filter((entry) => entry.isFile() && entry.name.toLowerCase().endsWith('.st'))
-            .map((entry) => entry.name);
+        const stFiles = this.listStructuredTextBundleFiles(sourcePath);
 
         if (stFiles.length === 0) {
             throw new Error(`No .st files found in source directory "${sourcePath}".`);
@@ -501,44 +498,28 @@ int main() {
     }
 
     detectCompiler(hostOs, hostArch, targetOs, targetArch) {
-        const hostDefaults = {
-            linux: "g++",
-            macos: "clang++",
-            windows: "cl.exe"
-        };
-        const hostKey = `${hostOs}-${hostArch}`;
         const targetKey = `${targetOs}-${targetArch}`;
 
         const ensureCompilerAvailable = (compilerName, message) => {
-            const versionCommand = compilerName === "cl.exe" ? compilerName : `${compilerName} --version`;
             try {
-                execSync(versionCommand, { stdio: "ignore" });
+                execSync(`"${compilerName}" --version`, { stdio: 'ignore' });
             } catch {
                 throw new Error(message);
             }
         };
 
-        if (targetKey === hostKey) {
-            const defaultCompiler = hostDefaults[hostOs];
-            if (!defaultCompiler) {
-                throw new Error(`No default compiler configured for host platform ${hostOs}.`);
-            }
-            ensureCompilerAvailable(
-                defaultCompiler,
-                `The default compiler "${defaultCompiler}" is not available. Install it using your package manager (e.g., brew install ${defaultCompiler} or apt install ${defaultCompiler}).
-                You can also create a file called "toolchain.json" in your source directory which will supply the path to the gnu c compiler for each platform. See the README file for more details.`
-            );
-            return defaultCompiler;
-        }
-
         const configuredCompiler = ToolChain[targetKey];
         if (!configuredCompiler) {
-            throw new Error(`No cross-compiler is configured for target ${targetKey}. Add it to toolchain.json or update the ToolChain defaults.`);
+            throw new Error(
+                `No toolchain is configured for target ${targetKey} on host ${hostOs}-${hostArch}. ` +
+                `Run "nodalis --action get-toolchains" or add an override in toolchain.json.`
+            );
         }
         ensureCompilerAvailable(
             configuredCompiler,
-            `Cross-compiler "${configuredCompiler}" for target ${targetKey} is not available. Install it via your package manager (e.g., brew install ${configuredCompiler} or apt install ${configuredCompiler}).
-                You can also create a file called "toolchain.json" in your source directory which will supply the path to the gnu c compiler for each platform. See the README file for more details.`
+            `Toolchain "${configuredCompiler}" for target ${targetKey} is not available. ` +
+            `Run "nodalis --action get-toolchains" to install managed toolchains under ${getToolchainRoot()}, ` +
+            `or add a custom compiler path in toolchain.json.`
         );
         return configuredCompiler;
     }
@@ -562,7 +543,7 @@ int main() {
         if (compiler === 'cl.exe') {
             return { c: [], cpp: [] };
         }
-        let flags = { //default flags are for macos clang
+        let flags = { // default flags are for managed/native clang wrappers
             'linux-x64': [],
             'linux-arm64': [],
             'linux-arm': [],
@@ -582,7 +563,18 @@ int main() {
             "macos-arm64": "",
         }
 
-        if (!compiler.includes("clang")) {
+        if (isManagedZigCompiler(compiler)) {
+            flags = {
+                'linux-x64': [],
+                'linux-arm64': [],
+                'linux-arm': [],
+                'macos-x64': [],
+                'macos-arm64': [],
+                'windows-x64': [],
+                'windows-arm64': []
+            };
+        }
+        else if (!compiler.includes("clang")) {
             flags = {
                 'linux-x64': ["-D_POSIX_C_SOURCE=200809L -D_GNU_SOURCE -pthread"],
                 'linux-arm64': ["-D_POSIX_C_SOURCE=200809L -D_GNU_SOURCE -pthread"],

package/src/compilers/Compiler.js

@@ -14,6 +14,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+import fs from 'fs';
 import path from 'path';
 
 export const IECLanguage = Object.freeze({
@@ -70,6 +71,26 @@ export class Compiler {
     return path.join(this.options.outputPath, 'bin');
   }
 
+  getStructuredTextBundleArtifactName() {
+    return 'nodalisplc.st';
+  }
+
+  cleanupStructuredTextBundleArtifacts(sourcePath) {
+    const artifactPath = path.join(sourcePath, this.getStructuredTextBundleArtifactName());
+    if (fs.existsSync(artifactPath) && fs.lstatSync(artifactPath).isFile()) {
+      fs.rmSync(artifactPath, { force: true });
+    }
+  }
+
+  listStructuredTextBundleFiles(sourcePath) {
+    const bundleArtifactName = this.getStructuredTextBundleArtifactName().toLowerCase();
+    return fs.readdirSync(sourcePath, { withFileTypes: true })
+      .filter((entry) => entry.isFile()
+        && entry.name.toLowerCase().endsWith('.st')
+        && entry.name.toLowerCase() !== bundleArtifactName)
+      .map((entry) => entry.name);
+  }
+
   /** @returns {string[]} */
   get supportedLanguages() {
     throw new Error('supportedLanguages must be implemented by subclass.');

package/src/compilers/JSCompiler.js

@@ -65,6 +65,7 @@ export class JSCompiler extends Compiler {
         let sourceCode = '';
         let bundleEntryProgram = '';
         if (directoryBundleMode) {
+            this.cleanupStructuredTextBundleArtifacts(sourcePath);
             const { combinedSource, entryProgramName } = this.loadStructuredTextBundle(sourcePath, resourceName);
             sourceCode = combinedSource;
             bundleEntryProgram = entryProgramName;
@@ -314,9 +315,7 @@ export function run(){
 }
 
 JSCompiler.prototype.loadStructuredTextBundle = function (sourcePath, resourceName) {
-    const stFiles = fs.readdirSync(sourcePath, { withFileTypes: true })
-        .filter((entry) => entry.isFile() && entry.name.toLowerCase().endsWith('.st'))
-        .map((entry) => entry.name);
+    const stFiles = this.listStructuredTextBundleFiles(sourcePath);
 
     if (stFiles.length === 0) {
         throw new Error(`No .st files found in source directory "${sourcePath}".`);

package/src/compilers/arduinoDefaults.js

@@ -0,0 +1,5 @@
+export const DEFAULT_ARDUINO_FQBN = {
+    'arduino-opta': 'arduino:mbed_opta:opta'
+};
+
+export const DEFAULT_ARDUINO_FQBNS = Object.values(DEFAULT_ARDUINO_FQBN);

package/src/compilers/support/arduino/nodalis.h

@@ -671,19 +671,12 @@ template <typename T, typename... Ts>
 inline T MUX(std::size_t K, T in0, Ts... rest)
 {
     constexpr std::size_t N = 1 + sizeof...(Ts);
+    T values[N] = {in0, static_cast<T>(rest)...};
     if (K >= N)
     {
-        throw std::out_of_range("MUX selector out of range");
+        return values[0];
     }
-
-    auto values = std::tuple<T, Ts...>(in0, rest...);
-    return std::apply(
-        [K](auto... elems) -> T
-        {
-            T arr[] = {elems...};
-            return arr[K];
-        },
-        values);
+    return values[K];
 };
 
 // ============================================================

package/src/nodalis.js

@@ -30,6 +30,7 @@ import { FileProgrammer } from './programmers/FileProgrammer.js';
 import { SSHProgrammer } from './programmers/SSHProgrammer.js';
 import { ArduinoProgrammer } from './programmers/ArduinoProgrammer.js';
 import { CompileList } from "mticp-npm"
+import { getToolchainRoot, installDefaultToolchains } from './toolchains.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -172,6 +173,10 @@ export class Nodalis {
     }
   }
 
+  async getToolchains() {
+    return installDefaultToolchains();
+  }
+
 }
 
 function isCliEntryPoint() {
@@ -221,6 +226,11 @@ Actions:
     --sshPort       Optional SSH port for SSH deployment.
     --arduinoFqbn   Required for Arduino target if --target Arduino.
 
+  --action get-toolchains
+      Detects the host OS/arch and installs managed C/C++ toolchains,
+      arduino-cli, and default Arduino board cores under:
+      ${getToolchainRoot()}
+
 Examples:
   node nodalis.js --action list-compilers
 
@@ -231,6 +241,8 @@ Examples:
     --resourceName MyPLC \\
     --sourcePath ./examples/pump.iec \\
     --language st
+
+  node nodalis.js --action get-toolchains
   `);
   process.exit(0);
 }
@@ -296,9 +308,18 @@ Examples:
       break;
     }
 
+    case 'get-toolchains': {
+      app.getToolchains().then((result) => {
+        console.log(JSON.stringify(result, null, 2));
+      }).catch(err => {
+        console.error(`Toolchain installation failed: ${err.message}`);
+      });
+      break;
+    }
+
     default: {
       console.error(`Unknown or missing action: ${argMap.action}`);
-      console.error(`Valid actions: list-compilers, list-programmers, compile, deploy`);
+      console.error(`Valid actions: list-compilers, list-programmers, compile, deploy, get-toolchains`);
       break;
     }
   }

package/src/programmers/ArduinoProgrammer.js

@@ -16,6 +16,7 @@ import fs from 'fs/promises';
 import path from 'path';
 import { Programmer } from './Programmer.js';
 import { runCommand } from './utils.js';
+import { getManagedArduinoCliExecOptions, getManagedArduinoCliPath } from '../toolchains.js';
 
 export class ArduinoProgrammer extends Programmer {
   constructor(options) {
@@ -58,7 +59,11 @@ export class ArduinoProgrammer extends Programmer {
       }
     }
 
-    const { stdout, stderr } = await runCommand('arduino-cli', args);
+    const { stdout, stderr } = await runCommand(
+      getManagedArduinoCliPath(),
+      args,
+      getManagedArduinoCliExecOptions()
+    );
     if (stdout) {
       console.log(stdout.trim());
     }

package/src/toolchains.js

@@ -0,0 +1,417 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import https from 'https';
+import { execFileSync } from 'child_process';
+import { pipeline } from 'stream/promises';
+import { DEFAULT_ARDUINO_FQBNS } from './compilers/arduinoDefaults.js';
+
+const ZIG_VERSION = '0.15.2';
+const ARDUINO_CLI_VERSION = '1.3.1';
+const TOOLCHAIN_ROOT = path.join(os.homedir(), '.nodalis', 'toolchains');
+const WRAPPER_EXTENSION = process.platform === 'win32' ? '.cmd' : '';
+const DEFAULT_ARDUINO_LIBRARIES = ['ArduinoModbus'];
+
+const TARGET_TRIPLES = {
+    'linux-arm': 'arm-linux-gnueabihf',
+    'linux-arm64': 'aarch64-linux-gnu',
+    'linux-x64': 'x86_64-linux-gnu',
+    'macos-arm64': 'aarch64-macos',
+    'macos-x64': 'x86_64-macos',
+    'windows-arm64': 'aarch64-windows-gnu',
+    'windows-x64': 'x86_64-windows-gnu'
+};
+
+const normalizeHostOS = (value) => {
+    if (value === 'win32') return 'windows';
+    if (value === 'darwin') return 'macos';
+    if (value === 'linux') return 'linux';
+    throw new Error(`Unsupported host operating system: ${value}`);
+};
+
+const normalizeHostArch = (value) => {
+    if (value === 'x64') return 'x64';
+    if (value === 'arm64') return 'arm64';
+    if (value.startsWith('arm')) return 'arm';
+    throw new Error(`Unsupported host architecture: ${value}`);
+};
+
+const stripArchiveExtension = (archiveName) => {
+    if (archiveName.endsWith('.tar.gz')) return archiveName.slice(0, -7);
+    if (archiveName.endsWith('.tar.xz')) return archiveName.slice(0, -7);
+    if (archiveName.endsWith('.zip')) return archiveName.slice(0, -4);
+    return archiveName;
+};
+
+const getWrapperDir = () => path.join(TOOLCHAIN_ROOT, 'zig', ZIG_VERSION, 'wrappers');
+
+const getWrapperPath = (target) => path.join(getWrapperDir(), `zig-${target}-c++${WRAPPER_EXTENSION}`);
+
+const getArduinoCliRootDir = () => path.join(TOOLCHAIN_ROOT, 'arduino-cli', ARDUINO_CLI_VERSION);
+
+const getArduinoCliDataDir = () => path.join(getArduinoCliRootDir(), 'data');
+
+const getArduinoCliDownloadsDir = () => path.join(getArduinoCliRootDir(), 'downloads');
+
+const getArduinoCliUserDir = () => path.join(getArduinoCliRootDir(), 'user');
+
+const getZigInstallDir = (host = detectHostPlatform()) => {
+    const archiveName = getZigArchiveName(host);
+    return path.join(TOOLCHAIN_ROOT, 'zig', ZIG_VERSION, stripArchiveExtension(archiveName));
+};
+
+const getZigBinaryPath = (host = detectHostPlatform()) => {
+    const installDir = getZigInstallDir(host);
+    return path.join(installDir, process.platform === 'win32' ? 'zig.exe' : 'zig');
+};
+
+const getArduinoCliArchiveName = (host = detectHostPlatform()) => {
+    if (host.os === 'windows') {
+        const archSegment = host.arch === 'arm64' ? 'Windows_ARM64' : host.arch === 'x64' ? 'Windows_64bit' : null;
+        if (!archSegment) {
+            throw new Error(`Unsupported Windows host architecture for arduino-cli: ${host.arch}`);
+        }
+        return `arduino-cli_${ARDUINO_CLI_VERSION}_${archSegment}.zip`;
+    }
+
+    if (host.os === 'macos') {
+        const archSegment = host.arch === 'arm64' ? 'macOS_ARM64' : host.arch === 'x64' ? 'macOS_64bit' : null;
+        if (!archSegment) {
+            throw new Error(`Unsupported macOS host architecture for arduino-cli: ${host.arch}`);
+        }
+        return `arduino-cli_${ARDUINO_CLI_VERSION}_${archSegment}.tar.gz`;
+    }
+
+    if (host.os === 'linux') {
+        if (host.arch === 'x64') return `arduino-cli_${ARDUINO_CLI_VERSION}_Linux_64bit.tar.gz`;
+        if (host.arch === 'arm64') return `arduino-cli_${ARDUINO_CLI_VERSION}_Linux_ARM64.tar.gz`;
+        if (host.arch === 'arm') return `arduino-cli_${ARDUINO_CLI_VERSION}_Linux_ARMv7.tar.gz`;
+    }
+
+    throw new Error(`Unsupported arduino-cli host platform ${host.os}-${host.arch}`);
+};
+
+const getArduinoCliInstallDir = (host = detectHostPlatform()) => {
+    return path.join(getArduinoCliRootDir(), `${host.os}-${host.arch}`);
+};
+
+export const getManagedArduinoCliPath = (host = detectHostPlatform()) => {
+    const installDir = getArduinoCliInstallDir(host);
+    return path.join(installDir, host.os === 'windows' ? 'arduino-cli.exe' : 'arduino-cli');
+};
+
+const getSupportedTargetsForHost = (host = detectHostPlatform()) => {
+    const targets = ['linux-arm', 'linux-arm64', 'linux-x64', 'windows-arm64', 'windows-x64'];
+    if (host.os === 'macos') {
+        targets.push('macos-arm64', 'macos-x64');
+    }
+    return targets;
+};
+
+const getZigArchiveName = (host = detectHostPlatform()) => {
+    if (host.os === 'windows') {
+        const archSegment = host.arch === 'arm64' ? 'aarch64' : host.arch === 'x64' ? 'x86_64' : null;
+        if (!archSegment) {
+            throw new Error(`Unsupported Windows host architecture for Zig: ${host.arch}`);
+        }
+        return `zig-${archSegment}-windows-${ZIG_VERSION}.zip`;
+    }
+
+    if (host.os === 'macos') {
+        const archSegment = host.arch === 'arm64' ? 'aarch64' : host.arch === 'x64' ? 'x86_64' : null;
+        if (!archSegment) {
+            throw new Error(`Unsupported macOS host architecture for Zig: ${host.arch}`);
+        }
+        return `zig-${archSegment}-macos-${ZIG_VERSION}.tar.xz`;
+    }
+
+    if (host.os === 'linux') {
+        if (host.arch === 'x64') return `zig-x86_64-linux-${ZIG_VERSION}.tar.xz`;
+        if (host.arch === 'arm64') return `zig-aarch64-linux-${ZIG_VERSION}.tar.xz`;
+        if (host.arch === 'arm') return `zig-arm-linux-${ZIG_VERSION}.tar.xz`;
+    }
+
+    throw new Error(`Unsupported Zig host platform ${host.os}-${host.arch}`);
+};
+
+const writeWrapper = (wrapperPath, zigBinaryPath, targetTriple) => {
+    fs.mkdirSync(path.dirname(wrapperPath), { recursive: true });
+
+    if (process.platform === 'win32') {
+        const windowsScript = [
+            '@echo off',
+            `"%~dp0..\\${path.basename(path.dirname(zigBinaryPath))}\\zig.exe" c++ -target ${targetTriple} %*`
+        ].join('\r\n');
+        fs.writeFileSync(wrapperPath, windowsScript);
+        return;
+    }
+
+    const posixScript = [
+        '#!/bin/sh',
+        `exec "${zigBinaryPath}" c++ -target ${targetTriple} "$@"`
+    ].join('\n');
+    fs.writeFileSync(wrapperPath, posixScript, { mode: 0o755 });
+    fs.chmodSync(wrapperPath, 0o755);
+};
+
+const ensureWrappers = (host = detectHostPlatform()) => {
+    const zigBinaryPath = getZigBinaryPath(host);
+    for (const target of getSupportedTargetsForHost(host)) {
+        const targetTriple = TARGET_TRIPLES[target];
+        if (!targetTriple) continue;
+        writeWrapper(getWrapperPath(target), zigBinaryPath, targetTriple);
+    }
+};
+
+export const detectHostPlatform = () => ({
+    os: normalizeHostOS(os.platform()),
+    arch: normalizeHostArch(os.arch())
+});
+
+export const getToolchainRoot = () => TOOLCHAIN_ROOT;
+
+export const getManagedArduinoCliExecOptions = (overrides = {}) => ({
+    ...overrides,
+    env: {
+        ...process.env,
+        ARDUINO_DIRECTORIES_DATA: getArduinoCliDataDir(),
+        ARDUINO_DIRECTORIES_DOWNLOADS: getArduinoCliDownloadsDir(),
+        ARDUINO_DIRECTORIES_USER: getArduinoCliUserDir(),
+        ...(overrides.env || {})
+    }
+});
+
+export const isManagedZigCompiler = (compilerPath) => String(compilerPath || '').includes(`${path.sep}.nodalis${path.sep}toolchains${path.sep}zig${path.sep}`);
+
+export const getDefaultToolchain = (host = detectHostPlatform()) => {
+    return getSupportedTargetsForHost(host).reduce((acc, target) => {
+        acc[target] = getWrapperPath(target);
+        return acc;
+    }, {});
+};
+
+const downloadFile = async (url, destinationPath) => {
+    await new Promise((resolve, reject) => {
+        const request = https.get(url, (response) => {
+            if (response.statusCode && response.statusCode >= 300 && response.statusCode < 400 && response.headers.location) {
+                response.resume();
+                downloadFile(response.headers.location, destinationPath).then(resolve).catch(reject);
+                return;
+            }
+
+            if (response.statusCode !== 200) {
+                response.resume();
+                reject(new Error(`Download failed with HTTP ${response.statusCode} for ${url}`));
+                return;
+            }
+
+            const fileStream = fs.createWriteStream(destinationPath);
+            pipeline(response, fileStream).then(resolve).catch(reject);
+        });
+
+        request.on('error', reject);
+    });
+};
+
+const extractArchive = (archivePath, destinationDir) => {
+    fs.mkdirSync(destinationDir, { recursive: true });
+
+    if (archivePath.endsWith('.zip')) {
+        if (process.platform !== 'win32') {
+            throw new Error(`ZIP extraction is only configured for Windows hosts: ${archivePath}`);
+        }
+
+        execFileSync(
+            'powershell.exe',
+            [
+                '-NoProfile',
+                '-NonInteractive',
+                '-Command',
+                `Expand-Archive -LiteralPath '${archivePath.replace(/'/g, "''")}' -DestinationPath '${destinationDir.replace(/'/g, "''")}' -Force`
+            ],
+            { stdio: 'inherit' }
+        );
+        return;
+    }
+
+    execFileSync('tar', ['-xf', archivePath, '-C', destinationDir], { stdio: 'inherit' });
+};
+
+const ensureArduinoCliDirs = () => {
+    fs.mkdirSync(getArduinoCliRootDir(), { recursive: true });
+    fs.mkdirSync(getArduinoCliDataDir(), { recursive: true });
+    fs.mkdirSync(getArduinoCliDownloadsDir(), { recursive: true });
+    fs.mkdirSync(getArduinoCliUserDir(), { recursive: true });
+};
+
+const installDefaultArduinoCores = (arduinoCliPath) => {
+    execFileSync(arduinoCliPath, ['core', 'update-index'], getManagedArduinoCliExecOptions({ stdio: 'inherit' }));
+
+    const coreIds = [...new Set(
+        DEFAULT_ARDUINO_FQBNS.map((fqbn) => {
+            const parts = String(fqbn).split(':');
+            return parts.length >= 2 ? `${parts[0]}:${parts[1]}` : null;
+        }).filter(Boolean)
+    )];
+
+    for (const coreId of coreIds) {
+        execFileSync(arduinoCliPath, ['core', 'install', coreId], getManagedArduinoCliExecOptions({ stdio: 'inherit' }));
+    }
+};
+
+const installDefaultArduinoLibraries = (arduinoCliPath) => {
+    for (const libraryName of DEFAULT_ARDUINO_LIBRARIES) {
+        execFileSync(
+            arduinoCliPath,
+            ['lib', 'install', libraryName],
+            getManagedArduinoCliExecOptions({ stdio: 'inherit' })
+        );
+    }
+};
+
+export const installDefaultToolchains = async () => {
+    const host = detectHostPlatform();
+    const archiveName = getZigArchiveName(host);
+    const rootDir = path.join(TOOLCHAIN_ROOT, 'zig', ZIG_VERSION);
+    const archivePath = path.join(rootDir, archiveName);
+    const installDir = getZigInstallDir(host);
+    const zigBinaryPath = getZigBinaryPath(host);
+
+    fs.mkdirSync(rootDir, { recursive: true });
+
+    const results = [];
+    if (!fs.existsSync(zigBinaryPath)) {
+        const downloadUrl = `https://ziglang.org/download/${ZIG_VERSION}/${archiveName}`;
+
+        try {
+            await downloadFile(downloadUrl, archivePath);
+            extractArchive(archivePath, rootDir);
+            fs.rmSync(archivePath, { force: true });
+            results.push({
+                id: 'zig',
+                status: 'installed',
+                installDir,
+                downloadUrl
+            });
+        } catch (err) {
+            fs.rmSync(archivePath, { force: true });
+            results.push({
+                id: 'zig',
+                status: 'failed',
+                downloadUrl,
+                error: err.message
+            });
+            return {
+                host,
+                rootDir: TOOLCHAIN_ROOT,
+                toolchains: results,
+                defaultToolchain: getDefaultToolchain(host)
+            };
+        }
+    } else {
+        results.push({
+            id: 'zig',
+            status: 'already-installed',
+            installDir
+        });
+    }
+
+    ensureWrappers(host);
+
+    const arduinoArchiveName = getArduinoCliArchiveName(host);
+    const arduinoRootDir = getArduinoCliRootDir();
+    const arduinoArchivePath = path.join(arduinoRootDir, arduinoArchiveName);
+    const arduinoInstallDir = getArduinoCliInstallDir(host);
+    const arduinoCliPath = getManagedArduinoCliPath(host);
+
+    ensureArduinoCliDirs();
+
+    if (!fs.existsSync(arduinoCliPath)) {
+        const downloadUrl = `https://downloads.arduino.cc/arduino-cli/${arduinoArchiveName}`;
+
+        try {
+            await downloadFile(downloadUrl, arduinoArchivePath);
+            fs.mkdirSync(arduinoInstallDir, { recursive: true });
+            extractArchive(arduinoArchivePath, arduinoInstallDir);
+            fs.rmSync(arduinoArchivePath, { force: true });
+            results.push({
+                id: 'arduino-cli',
+                status: 'installed',
+                installDir: arduinoInstallDir,
+                downloadUrl
+            });
+        } catch (err) {
+            fs.rmSync(arduinoArchivePath, { force: true });
+            results.push({
+                id: 'arduino-cli',
+                status: 'failed',
+                downloadUrl,
+                error: err.message
+            });
+            return {
+                host,
+                rootDir: TOOLCHAIN_ROOT,
+                toolchains: results,
+                defaultToolchain: getDefaultToolchain(host),
+                arduinoCli: arduinoCliPath,
+                defaultArduinoFqbns: DEFAULT_ARDUINO_FQBNS
+            };
+        }
+    } else {
+        results.push({
+            id: 'arduino-cli',
+            status: 'already-installed',
+            installDir: arduinoInstallDir
+        });
+    }
+
+    try {
+        installDefaultArduinoCores(arduinoCliPath);
+        results.push({
+            id: 'arduino-default-cores',
+            status: 'installed',
+            fqbns: DEFAULT_ARDUINO_FQBNS
+        });
+    } catch (err) {
+        results.push({
+            id: 'arduino-default-cores',
+            status: 'failed',
+            fqbns: DEFAULT_ARDUINO_FQBNS,
+            error: err.message
+        });
+    }
+
+    try {
+        installDefaultArduinoLibraries(arduinoCliPath);
+        results.push({
+            id: 'arduino-default-libraries',
+            status: 'installed',
+            libraries: DEFAULT_ARDUINO_LIBRARIES
+        });
+    } catch (err) {
+        results.push({
+            id: 'arduino-default-libraries',
+            status: 'failed',
+            libraries: DEFAULT_ARDUINO_LIBRARIES,
+            error: err.message
+        });
+    }
+
+    return {
+        host,
+        rootDir: TOOLCHAIN_ROOT,
+        toolchains: [
+            ...results,
+            ...getSupportedTargetsForHost(host).map((target) => ({
+                id: target,
+                status: 'ready',
+                compiler: getWrapperPath(target),
+                targetTriple: TARGET_TRIPLES[target]
+            }))
+        ],
+        defaultToolchain: getDefaultToolchain(host),
+        arduinoCli: arduinoCliPath,
+        defaultArduinoFqbns: DEFAULT_ARDUINO_FQBNS,
+        defaultArduinoLibraries: DEFAULT_ARDUINO_LIBRARIES
+    };
+};