@typecad/framework-zephyr 1.0.0-alpha.10

package/dist/toolchain/scaffold.js

@@ -0,0 +1,196 @@
+// ---------------------------------------------------------------------------
+// Zephyr project scaffolding
+//
+// Writes the CMakeLists.txt + prj.conf around the cuttlefish-emitted src/main.cpp
+// so `west build` has a valid Zephyr application. Idempotent: overwrites the
+// generated files only when their content changes (avoids invalidating the
+// Ninja incremental build's mtime-based dependency tracking).
+// ---------------------------------------------------------------------------
+import { writeFileSync, existsSync, mkdirSync, readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { resolveKconfigFragments } from '../dt-config/kconfig.js';
+/** Write a file only if the content differs from the existing file.
+ *  Returns true when the file was written (content changed or file was new). */
+export function writeIfChanged(filePath, content) {
+    if (existsSync(filePath)) {
+        try {
+            if (readFileSync(filePath, 'utf8') === content)
+                return false;
+        }
+        catch {
+            // Read failed — fall through to write.
+        }
+    }
+    writeFileSync(filePath, content);
+    return true;
+}
+/**
+ * Concatenate all emitted source under src/ so the scaffold can detect which
+ * peripherals the program actually uses. The cuttlefish lowering emits
+ * well-known driver API tokens (adc_read, spi_transceive, bt_*, …), so scanning
+ * the post-transpile source is an authoritative usage signal — and it keeps the
+ * scaffold self-contained (no need to thread analysis through the toolchain
+ * contract). Returns '' when no sources exist yet (first prepare call).
+ */
+function readEmittedSources(srcDir) {
+    if (!existsSync(srcDir))
+        return '';
+    let out = '';
+    for (const name of readdirSync(srcDir)) {
+        if (name.endsWith('.cpp') || name.endsWith('.c')) {
+            try {
+                out += readFileSync(join(srcDir, name), 'utf8');
+            }
+            catch {
+                // ignore unreadable files
+            }
+        }
+    }
+    return out;
+}
+/**
+ * Emit the Zephyr application skeleton around the generated src/main.cpp.
+ *
+ * Layout written:
+ *   <projectRoot>/
+ *     CMakeLists.txt   (find_package(Zephyr), target_sources app ← src/*.cpp)
+ *     prj.conf         (CONFIG_* for GPIO + C++ + libc)
+ *     src/main.cpp     (owned by cuttlefish's emit pipeline — NOT touched here)
+ *
+ * Idempotent. Mirrors scaffoldEspIdfProject's writeIfChanged discipline.
+ */
+export function scaffoldZephyrProject(projectRoot, debug = false, userKconfig, psram) {
+    const srcDir = join(projectRoot, 'src');
+    if (!existsSync(srcDir))
+        mkdirSync(srcDir, { recursive: true });
+    // Detect which peripherals the program actually uses by scanning the emitted
+    // source. The cuttlefish lowering emits well-known driver API tokens, so this
+    // is authoritative. Usage-gating the Kconfig symbols keeps a GPIO-only
+    // program from pulling in (and linking) stacks it doesn't need — notably
+    // NimBLE (CONFIG_BT), whose Espressif prebuilt blobs are not always present
+    // in a workspace. The symbol set itself lives in resolveKconfigFragments
+    // (dt-config/kconfig.ts), unit-tested separately.
+    const src = readEmittedSources(srcDir);
+    // Boundary-anchored token scan: a bare `src.includes('power_')` would match
+    // `tx_power_dbm` (emitted by the WiFi shim) and flip CONFIG_PM on for a
+    // WiFi-only program — on the ESP32-S3 that spins the PM soft-off retry loop
+    // forever and starves the app. Anchor each `<prefix>_` token at a leading
+    // word boundary so it matches the intended driver/HAL symbol, not a suffix.
+    const uses = (token) => {
+        if (token.endsWith('_')) {
+            return new RegExp(`\\b${token.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}`).test(src);
+        }
+        return src.includes(token);
+    };
+    const usage = {
+        usesAdc: uses('adc_'),
+        usesPwm: uses('pwm_'),
+        usesI2c: uses('i2c_'),
+        usesSpi: uses('spi_'),
+        usesUart: uses('uart_'),
+        usesWdt: uses('wdt_'),
+        usesBle: uses('bt_') || uses('bt_gatt') || uses('bt_le_'),
+        usesDisplay: uses('display_write') || uses('display_init') || uses('display_fill_rect') || uses('__tc_display_dev') || uses('CuttlefishDisplayTarget'),
+        usesTouch: uses('ft6336u') || uses('touch_'),
+        // Power tokens: k_sleep + pm_state_force / PM_STATE_* (what power.ts emits).
+        // The old `power_` token matched nothing the power HAL emits and collides
+        // with tx_power_dbm — removed.
+        usesPower: uses('pm_') || uses('k_sleep') || uses('PM_STATE_'),
+        usesWifi: uses('wifi_') || uses('net_mgmt') || uses('conn_mgr'),
+        // HTTP: the __tc_http_* shim + http_client_req + getaddrinfo. The '_'-anchored
+        // 'http_' token matches __tc_http_* and http_client_req (the core HTTP lib
+        // symbol), mirroring how wifi_ detects the wifi shim. An http-only program
+        // still pulls the networking stack even without usesWifi.
+        usesHttp: uses('http_') || uses('__tc_http') || uses('http_client_req'),
+        // MQTT: the __tc_mqtt_* shim + mqtt_connect/mqtt_publish/mqtt_subscribe.
+        usesMqtt: uses('mqtt_') || uses('__tc_mqtt') || uses('mqtt_connect'),
+        // Preferences: the __tc_prefs_* shim + the settings_* API the shim calls.
+        // settings_load/save_one/delete + SETTINGS_STATIC_HANDLER_DEFINE all emit
+        // `settings_` symbols; __tc_prefs catches the typed accessors (put_int etc.
+        // template into __tc_prefs_put<...>, which keeps the __tc_prefs token).
+        usesPreferences: uses('settings_') || uses('__tc_prefs'),
+        // Random: the __tc_rand_* shim + the sys_rand_get entropy tap it seeds from.
+        usesRandom: uses('__tc_rand') || uses('sys_rand_get'),
+        psram,
+    };
+    let changed = false;
+    // ── Root CMakeLists.txt ─────────────────────────────────────────────────
+    // The canonical Zephyr CMake application. GLOB src/*.cpp so future multi-
+    // file emits are picked up automatically; cuttlefish owns the file contents.
+    const cmakeLists = [
+        '# Auto-generated by @typecad/framework-zephyr from cuttlefish.config.ts.',
+        'cmake_minimum_required(VERSION 3.20.0)',
+        '',
+        'find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE})',
+        '',
+        'project(zephyr_app)',
+        '',
+        '# Collect cuttlefish-emitted sources.',
+        'file(GLOB app_sources src/*.cpp src/*.c)',
+        '',
+        'target_sources(app PRIVATE ${app_sources})',
+        // When PSRAM is configured, define BOARD_HAS_PSRAM so the UI runtime's
+        // PSRAM canvas allocator (ui_create_canvas_best) is compiled in.
+        ...(psram ? ['', '# PSRAM enabled: activate the runtime PSRAM canvas paths.', 'target_compile_definitions(app PRIVATE BOARD_HAS_PSRAM)', ''] : ['']),
+    ].join('\n');
+    if (writeIfChanged(join(projectRoot, 'CMakeLists.txt'), cmakeLists))
+        changed = true;
+    // ── prj.conf ────────────────────────────────────────────────────────────
+    // Driver Kconfig symbols are usage-gated on the emitted source: only a
+    // peripheral whose driver API the program actually references is enabled.
+    // Zephyr's Kconfig treats an enabled-but-unused driver as harmless, BUT
+    // several driver stacks pull in large/specific dependencies — notably
+    // NimBLE (CONFIG_BT) needs Espressif prebuilt blobs that are not always
+    // fetched (`west blobs fetch hal_espressif`). Usage-gating keeps a GPIO-only
+    // blink from requiring those, and shrinks the link for every program. The
+    // core GPIO driver and C++ support stay unconditional. Symbol selection is
+    // delegated to resolveKconfigFragments (unit-tested in dt-config/kconfig).
+    const symbols = resolveKconfigFragments(usage, debug);
+    const prjConf = [
+        '# Auto-generated by @typecad/framework-zephyr from cuttlefish.config.ts.',
+        '# Edit in cuttlefish.config.ts (frameworkData), not here.',
+        '# Driver symbols are usage-gated on the emitted source — only peripherals',
+        '# the program references are enabled.',
+        '',
+        '# Route printf/stdout to the console UART (needed by the @typecad/expect',
+        '# test runner protocol, which uses printf via __tc_print/__tc_println).',
+        'CONFIG_STDOUT_CONSOLE=y',
+        'CONFIG_PRINTK=y',
+        '',
+    ];
+    // Emit a section header before the BT block when present.
+    let btHeaderEmitted = false;
+    let wifiHeaderEmitted = false;
+    for (const [sym, val] of symbols) {
+        if (sym === 'CONFIG_BT' && !btHeaderEmitted) {
+            prjConf.push('', '# Bluetooth (NimBLE peripheral).');
+            btHeaderEmitted = true;
+        }
+        if (sym === 'CONFIG_WIFI' && !wifiHeaderEmitted) {
+            prjConf.push('', '# WiFi / networking (conn_mgr + esp32 wifi driver).');
+            wifiHeaderEmitted = true;
+        }
+        // Skip auto-detected symbols that the user explicitly overrides
+        // in cuttlefish.config.ts zephyr.kconfig — the user value is
+        // emitted in the User Kconfig section below and takes precedence.
+        if (userKconfig && userKconfig.hasOwnProperty(sym))
+            continue;
+        prjConf.push(`${sym}=${val}`);
+    }
+    // Emit user-specified Kconfig from cuttlefish.config.ts zephyr.kconfig.
+    // These override any matching auto-detected symbol (skipped above).
+    if (userKconfig) {
+        prjConf.push('', '# User Kconfig (cuttlefish.config.ts → zephyr.kconfig).');
+        for (const [sym, val] of Object.entries(userKconfig)) {
+            prjConf.push(`${sym}=${val}`);
+        }
+    }
+    // CONFIG_BT_DEVICE_NAME is a string value not produced by the resolver — add
+    // it after the BT block when BLE is used (parity with the previous inline form).
+    if (usage.usesBle)
+        prjConf.push('CONFIG_BT_DEVICE_NAME="TypeCAD"');
+    prjConf.push('');
+    if (writeIfChanged(join(projectRoot, 'prj.conf'), prjConf.join('\n')))
+        changed = true;
+    return changed;
+}

package/dist/toolchain/west-discover.d.ts

@@ -0,0 +1,40 @@
+/**
+ * A discovered, usable west installation. `mode` tells the caller how to
+ * invoke it: 'launcher' = call `westExecutable` directly; 'module' = call
+ * `pythonExecutable -m west`.
+ */
+export interface WestInstall {
+    mode: 'launcher' | 'module';
+    /** Absolute path to a `west` launcher (mode 'launcher') or undefined. */
+    westExecutable?: string;
+    /** Absolute path to a Python interpreter with west installed (mode 'module'). */
+    pythonExecutable?: string;
+    /** Absolute path to the Zephyr SDK root (for $ZEPHYR_BASE), if found. */
+    zephyrBase?: string;
+    /** Which discovery strategy found this install. */
+    source: 'path' | 'zephyr-base-venv' | 'well-known' | 'system-python';
+}
+/** True if `dir` looks like a Zephyr SDK root: has CMakeLists.txt and the
+ *  kernel header. */
+export declare function isZephyrBase(dir: string): boolean;
+export declare function discoverFromPath(): WestInstall | null;
+/** The canonical Zephyr workspace layout puts the venv beside the SDK:
+ *  <workspace>/{.venv, zephyr}. So ${ZEPHYR_BASE}/../.venv is the venv. */
+export declare function discoverFromZephyrBase(): WestInstall | null;
+/** Candidate Zephyr workspace directories. Each may contain both `.venv/`
+ *  and `zephyr/` (the SDK). Exported for test injection. */
+export declare function wellKnownWorkspaces(): string[];
+export declare function discoverFromWellKnown(workspaces?: string[]): WestInstall | null;
+/** Candidate system Python interpreters to probe with `-m west`. */
+export declare function systemPythons(): string[];
+export declare function discoverFromSystemPython(pythons?: string[]): WestInstall | null;
+/** Clear the process-local discovery cache (for tests). */
+export declare function resetWestDiscoveryCache(): void;
+/**
+ * Try each discovery strategy in order. The first usable install wins.
+ * Result is memoized for the process lifetime (west installs don't move).
+ *
+ * Order: PATH → $ZEPHYR_BASE venv → well-known workspaces → system pythons.
+ * Returns null when no usable west install is found.
+ */
+export declare function discoverWest(): WestInstall | null;

package/dist/toolchain/west-discover.js

@@ -0,0 +1,203 @@
+// ---------------------------------------------------------------------------
+// west discovery — find a usable `west` (and the Zephyr SDK / ZEPHYR_BASE)
+//
+// west installs into a Python venv that must be activated before `west` is on
+// PATH. We resolve a working invocation WITHOUT requiring the user to have
+// activated the venv, by preferring the robust `<python> -m west` form: it
+// sidesteps shebang-launcher fragility on Windows and works with any venv
+// once we know which Python interpreter has west installed.
+//
+// Discovery cascade (first usable wins):
+//   1. `west` already on PATH (env already activated / global install).
+//   2. $ZEPHYR_BASE venv: ${ZEPHYR_BASE}/../.venv/<python> -m west.
+//   3. Well-known workspace layouts: ~/zephyrproject/.venv, /opt/zephyrproject/.
+//      venv, etc.
+//   4. System pythons (`python`, `python3`, `py`) via `-m west`.
+//
+// Leaner than the ESP-IDF equivalent: west needs no env sourcing (no 15s
+// export.sh) — only the right interpreter + ZEPHYR_BASE.
+// ---------------------------------------------------------------------------
+import { existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { homedir } from 'node:os';
+import { spawnSync } from 'node:child_process';
+const IS_WIN = process.platform === 'win32';
+/** The Python executable name inside a venv's bin/ (POSIX) or Scripts/ (Win). */
+function venvPython(venvDir) {
+    return join(venvDir, IS_WIN ? 'Scripts' : 'bin', IS_WIN ? 'python.exe' : 'python');
+}
+/** True if `exe` runs `python -m west --version` successfully. */
+function pythonRunsWest(exe) {
+    try {
+        const r = spawnSync(exe, ['-m', 'west', '--version'], {
+            encoding: 'utf8',
+            timeout: 15_000,
+            windowsHide: true,
+        });
+        return r.status === 0;
+    }
+    catch {
+        return false;
+    }
+}
+/** True if `cmd` runs `west --version` successfully. */
+function westOnPath(cmd) {
+    try {
+        const r = spawnSync(cmd, ['--version'], {
+            encoding: 'utf8',
+            timeout: 15_000,
+            shell: IS_WIN,
+            windowsHide: true,
+        });
+        return r.status === 0;
+    }
+    catch {
+        return false;
+    }
+}
+/** True if `dir` looks like a Zephyr SDK root: has CMakeLists.txt and the
+ *  kernel header. */
+export function isZephyrBase(dir) {
+    if (!dir)
+        return false;
+    return (existsSync(join(dir, 'CMakeLists.txt')) &&
+        existsSync(join(dir, 'include', 'zephyr', 'kernel.h')));
+}
+// ── Strategy 1: `west` on PATH ──────────────────────────────────────────────
+export function discoverFromPath() {
+    const which = spawnSync(IS_WIN ? 'where' : 'which', ['west'], {
+        encoding: 'utf8',
+        shell: true,
+        windowsHide: true,
+    });
+    if (which.status !== 0)
+        return null;
+    const lines = (which.stdout ?? '').split(/\r?\n/).map((s) => s.trim()).filter(Boolean);
+    for (const line of lines) {
+        if (!existsSync(line))
+            continue;
+        if (!westOnPath(line))
+            continue;
+        return {
+            mode: 'launcher',
+            westExecutable: line,
+            zephyrBase: process.env.ZEPHYR_BASE || undefined,
+            source: 'path',
+        };
+    }
+    return null;
+}
+// ── Strategy 2: $ZEPHYR_BASE sibling venv ───────────────────────────────────
+/** The canonical Zephyr workspace layout puts the venv beside the SDK:
+ *  <workspace>/{.venv, zephyr}. So ${ZEPHYR_BASE}/../.venv is the venv. */
+export function discoverFromZephyrBase() {
+    const zb = process.env.ZEPHYR_BASE;
+    if (!zb || !isZephyrBase(zb))
+        return null;
+    const workspaceDir = dirname(zb);
+    const venvDir = join(workspaceDir, '.venv');
+    const py = venvPython(venvDir);
+    if (!existsSync(py) || !pythonRunsWest(py))
+        return null;
+    return {
+        mode: 'module',
+        pythonExecutable: py,
+        zephyrBase: zb,
+        source: 'zephyr-base-venv',
+    };
+}
+// ── Strategy 3: well-known workspace layouts ───────────────────────────────
+/** Candidate Zephyr workspace directories. Each may contain both `.venv/`
+ *  and `zephyr/` (the SDK). Exported for test injection. */
+export function wellKnownWorkspaces() {
+    const home = homedir();
+    if (IS_WIN) {
+        return [
+            join(home, 'zephyrproject'),
+            join(home, 'zephyr'),
+            'C:\\zephyrproject',
+            'C:\\zephyr',
+        ];
+    }
+    return [
+        join(home, 'zephyrproject'),
+        join(home, 'zephyr'),
+        '/opt/zephyrproject',
+        '/opt/zephyr',
+    ];
+}
+export function discoverFromWellKnown(workspaces = wellKnownWorkspaces()) {
+    for (const ws of workspaces) {
+        const venvDir = join(ws, '.venv');
+        const py = venvPython(venvDir);
+        if (!existsSync(py) || !pythonRunsWest(py))
+            continue;
+        // Resolve ZEPHYR_BASE if the SDK sits beside the venv.
+        const zb = join(ws, 'zephyr');
+        return {
+            mode: 'module',
+            pythonExecutable: py,
+            zephyrBase: isZephyrBase(zb) ? zb : undefined,
+            source: 'well-known',
+        };
+    }
+    return null;
+}
+// ── Strategy 4: system pythons via `-m west` ────────────────────────────────
+/** Candidate system Python interpreters to probe with `-m west`. */
+export function systemPythons() {
+    if (IS_WIN)
+        return ['py', 'python', 'python3'];
+    return ['python3', 'python'];
+}
+export function discoverFromSystemPython(pythons = systemPythons()) {
+    for (const py of pythons) {
+        if (!pythonRunsWest(py))
+            continue;
+        return {
+            mode: 'module',
+            pythonExecutable: py,
+            zephyrBase: process.env.ZEPHYR_BASE || undefined,
+            source: 'system-python',
+        };
+    }
+    return null;
+}
+// ── Top-level cascade ────────────────────────────────────────────────────────
+let cachedDiscover;
+/** Clear the process-local discovery cache (for tests). */
+export function resetWestDiscoveryCache() {
+    cachedDiscover = undefined;
+}
+/**
+ * Try each discovery strategy in order. The first usable install wins.
+ * Result is memoized for the process lifetime (west installs don't move).
+ *
+ * Order: PATH → $ZEPHYR_BASE venv → well-known workspaces → system pythons.
+ * Returns null when no usable west install is found.
+ */
+export function discoverWest() {
+    if (cachedDiscover !== undefined)
+        return cachedDiscover;
+    const strategies = [
+        discoverFromPath,
+        discoverFromZephyrBase,
+        discoverFromWellKnown,
+        discoverFromSystemPython,
+    ];
+    for (const strat of strategies) {
+        let install = null;
+        try {
+            install = strat();
+        }
+        catch {
+            install = null;
+        }
+        if (install) {
+            cachedDiscover = install;
+            return install;
+        }
+    }
+    cachedDiscover = null;
+    return null;
+}

package/dist/toolchain/west-spawn.d.ts

@@ -0,0 +1,39 @@
+import type { SpawnSyncOptions } from 'node:child_process';
+import { type WestInstall } from './west-discover.js';
+export interface WestInvocation {
+    /** The command to spawnSync: a `west` launcher or a Python interpreter. */
+    command: string;
+    /** Args for the command (includes `-m west` when in module mode). */
+    args: string[];
+    /** Base spawn options with cwd/timeout/encoding/stdio, plus the env carrying
+     *  ZEPHYR_BASE when discovered. */
+    options: SpawnSyncOptions;
+    /** The install the invocation was built from, for surfacing to the user. */
+    install: WestInstall;
+}
+/**
+ * The env to pass to the west spawn: the process env, with ZEPHYR_BASE injected
+ * when a SDK root was discovered, AND the venv's bin/Scripts dir prepended to
+ * PATH when west was found via a venv Python.
+ *
+ * The PATH prepend matters: `west flash` shells out to bare runner tools
+ * (`esptool`, `openocd`, `nrfjprog`, …) via check_call, so they resolve from
+ * PATH. Without the prepend, the user's PATH may surface a *different* tool
+ * ahead of the venv's — e.g. an older esptool whose argument spelling is
+ * incompatible with the runner. Putting the venv's bin first makes west's
+ * delegated subprocesses resolve to the same versions west itself runs under.
+ */
+export declare function buildEnv(install: WestInstall): NodeJS.ProcessEnv;
+/**
+ * Build a spawn invocation that runs `west <westArgs>`.
+ *
+ * `baseOptions` carries the cwd/timeout/stdio settings the caller wants;
+ * westSpawn preserves them and injects the discovery env. The returned object
+ * destructures directly into spawnSync:
+ *
+ *   const inv = westSpawn(['build', '-b', 'xiao_ble', projectRoot], { cwd, timeout });
+ *   spawnSync(inv.command, inv.args, inv.options);
+ *
+ * Throws a clear, actionable error when no usable west install is discovered.
+ */
+export declare function westSpawn(westArgs: string[], baseOptions: SpawnSyncOptions): WestInvocation;

package/dist/toolchain/west-spawn.js

@@ -0,0 +1,117 @@
+// ---------------------------------------------------------------------------
+// west spawn helper — build a spawnSync invocation for `west <args>`
+//
+// Mirrors framework-esp32's idfSpawn(): given the discovered WestInstall,
+// produce {command, args, env} that the toolchain destructures into spawnSync.
+//
+// Two modes:
+//   - 'launcher': spawn the `west` launcher directly (mode 'launcher').
+//   - 'module'  : spawn `<python> -m west ...` (mode 'module'). This is the
+//                 robust cross-platform form — it activates the venv's
+//                 interpreter for the one process without sourcing anything.
+//
+// ZEPHYR_BASE is injected into the spawn env when a SDK root was discovered
+// (find_package(Zephyr) needs it). west's prj.conf/CMakeLists are found via
+// the project dir regardless.
+// ---------------------------------------------------------------------------
+import { dirname } from 'node:path';
+import { discoverWest } from './west-discover.js';
+/**
+ * The Scripts/ (Windows) or bin/ (POSIX) directory of the venv the discovered
+ * west runs under. `pythonExecutable` lives in that directory, so it is its
+ * dirname. Returns undefined for launcher-mode installs where no venv is known.
+ */
+function venvBinDir(install) {
+    return install.pythonExecutable ? dirname(install.pythonExecutable) : undefined;
+}
+/**
+ * The env to pass to the west spawn: the process env, with ZEPHYR_BASE injected
+ * when a SDK root was discovered, AND the venv's bin/Scripts dir prepended to
+ * PATH when west was found via a venv Python.
+ *
+ * The PATH prepend matters: `west flash` shells out to bare runner tools
+ * (`esptool`, `openocd`, `nrfjprog`, …) via check_call, so they resolve from
+ * PATH. Without the prepend, the user's PATH may surface a *different* tool
+ * ahead of the venv's — e.g. an older esptool whose argument spelling is
+ * incompatible with the runner. Putting the venv's bin first makes west's
+ * delegated subprocesses resolve to the same versions west itself runs under.
+ */
+export function buildEnv(install) {
+    const env = { ...process.env };
+    if (install.zephyrBase && !env.ZEPHYR_BASE) {
+        env.ZEPHYR_BASE = install.zephyrBase;
+    }
+    const bin = venvBinDir(install);
+    if (bin) {
+        const sep = process.platform === 'win32' ? ';' : ':';
+        // On Windows the PATH environment variable may be cased as `Path` (the
+        // registry-native form, the only one populated when node is launched from
+        // PowerShell/cmd) or `PATH` (POSIX form, set by Git Bash). Writing only one
+        // casing can leave the other stale/empty, which under PowerShell would drop
+        // the user's real PATH (cmake, ninja, …) — breaking `west` configure. Read
+        // whichever casing is populated and write that same casing back, preserving
+        // the full existing value with the venv dir prepended.
+        const existing = env.Path ?? env.PATH ?? '';
+        const updated = bin + sep + existing;
+        if (env.Path !== undefined || (env.PATH === undefined && process.platform === 'win32')) {
+            env.Path = updated;
+        }
+        else {
+            env.PATH = updated;
+        }
+    }
+    return env;
+}
+/**
+ * Build a spawn invocation that runs `west <westArgs>`.
+ *
+ * `baseOptions` carries the cwd/timeout/stdio settings the caller wants;
+ * westSpawn preserves them and injects the discovery env. The returned object
+ * destructures directly into spawnSync:
+ *
+ *   const inv = westSpawn(['build', '-b', 'xiao_ble', projectRoot], { cwd, timeout });
+ *   spawnSync(inv.command, inv.args, inv.options);
+ *
+ * Throws a clear, actionable error when no usable west install is discovered.
+ */
+export function westSpawn(westArgs, baseOptions) {
+    const install = discoverWest();
+    if (!install) {
+        throw new Error([
+            'west (the Zephyr build tool) was not found.',
+            '',
+            'cuttlefish looked for it on PATH, in $ZEPHYR_BASE/.venv, in common',
+            'Zephyr workspace dirs (~/zephyrproject/.venv), and as a system',
+            "Python module (`python -m west`). To fix:",
+            '',
+            '  • Run the typeCAD Zephyr installer (one command, any OS — needs Node ≥18):',
+            '      node packages/zephyr-installer/install.mjs',
+            '    then `micromamba activate zephyr` and retry.',
+            '  • Or activate an existing Zephyr venv in this shell, or',
+            '  • Or set ZEPHYR_BASE to your Zephyr SDK root (the venv at $ZEPHYR_BASE/../.venv is then used), or',
+            '  • Or install west into a discoverable Python: pip install west',
+            '',
+            'See https://docs.zephyrproject.org/latest/develop/getting_started/index.html',
+        ].join('\n'));
+    }
+    const env = buildEnv(install);
+    // Strip `shell` if present — we pass absolute paths / known commands, and
+    // an explicit shell changes arg-quoting semantics on Windows.
+    const { shell: _drop, ...optsWithoutShell } = baseOptions;
+    if (install.mode === 'launcher' && install.westExecutable) {
+        return {
+            command: install.westExecutable,
+            args: westArgs,
+            options: { ...optsWithoutShell, env },
+            install,
+        };
+    }
+    // module mode: <python> -m west <args>
+    const py = install.pythonExecutable;
+    return {
+        command: py,
+        args: ['-m', 'west', ...westArgs],
+        options: { ...optsWithoutShell, env },
+        install,
+    };
+}