@typecad/framework-zephyr 1.0.0-alpha.8

package/dist/toolchain/index.js

@@ -0,0 +1,427 @@
+// ---------------------------------------------------------------------------
+// FrameworkToolchain impl for Zephyr (west / CMake)
+//
+// compile() scaffolds the project (idempotent) then runs `west build -b <board>`.
+// upload() runs `west flash`. monitor() runs a best-effort serial monitor.
+//
+// west resolution goes through westSpawn(), which finds a usable west without
+// requiring the user to have activated the Zephyr Python venv — it prefers
+// `<python> -m west` (robust cross-platform form) and injects ZEPHYR_BASE when
+// a SDK root is discovered. See west-discover.ts / west-spawn.ts.
+//
+// The board target is carried via frameworkData.buildTarget (populated as
+// ToolchainOptions.buildTarget by the cuttlefish CLI), defaulting to the
+// framework's canonical MVP target (xiao_ble).
+//
+// Mirrors framework-esp32/src/toolchain/index.ts structure: projectRoot derived
+// from outputDir, prepare is a no-op (scaffold happens in compile when the
+// target is known), GCC errors parsed via the shared parseCompileErrors helper.
+// ---------------------------------------------------------------------------
+import { spawnSync } from 'node:child_process';
+import { basename, dirname, join } from 'node:path';
+import { readdirSync, readFileSync, mkdirSync, rmSync, existsSync } from 'node:fs';
+import { parseCompileErrors } from '@typecad/cuttlefish/api/shared';
+import { scaffoldZephyrProject, writeIfChanged } from './scaffold.js';
+import { westSpawn, buildEnv } from './west-spawn.js';
+import { discoverWest } from './west-discover.js';
+import { writeDebugConfig, resolveDebugLocations } from './debug-config.js';
+import { ZephyrStrategy } from '../strategy.js';
+import { generateOverlay } from '../dt-config/overlay.js';
+import { chipForTarget } from '../chips/index.js';
+import { DEFAULT_ZEPHYR_DISPLAY_PROFILE } from '../display/profiles.js';
+/** Default board target — the framework's MVP canonical board. */
+const DEFAULT_BOARD = 'xiao_ble';
+function targetFromOptions(o) {
+    // The cuttlefish CLI populates ToolchainOptions.buildTarget from
+    // config.frameworkData.buildTarget. Accept frameworkData.target as an alias.
+    const fcTarget = o.frameworkConfig?.target;
+    return o.buildTarget ?? fcTarget ?? DEFAULT_BOARD;
+}
+/**
+ * Derive the Zephyr project root from the cuttlefish-emitted source path.
+ *
+ * Cuttlefish emits `src/main.cpp` under the output dir. The CLI passes
+ * `sourcePath` = full path to `main.cpp` and `outputDir` = its parent (`src/`).
+ * For Zephyr, the project root is the parent of `src/` — one level above
+ * `outputDir`. Detect that shape and adjust; otherwise fall back to `outputDir`.
+ */
+export function projectRootFromOptions(o) {
+    const outDir = o.outputDir;
+    if (basename(outDir) === 'src') {
+        return dirname(outDir);
+    }
+    return outDir;
+}
+/**
+ * west build timeout. Zephyr's first build fetches the toolchain modules and
+ * configures CMake/Ninja, which can take several minutes; allow generous headroom.
+ */
+const BUILD_TIMEOUT_MS = 600_000;
+const FLASH_TIMEOUT_MS = 120_000;
+/**
+ * Build the `west flash` argument list for a board.
+ *
+ * Runner selection: each board's board.cmake declares a sensible default flash
+ * runner for its hardware (xiao_ble → nrfutil, esp32* → esptool), and `west
+ * flash` resolves it automatically. The framework only intervenes where the
+ * board default needs an argument it can't infer:
+ *   - An explicit `zephyr.runner` (from cuttlefish.config.ts) always wins.
+ *   - ESP32 boards forward the port via `--esp-device` (esptool reads the
+ *     device from it); board.cmake still picks the runner.
+ *   - Every other board trusts the board.cmake default. Previously this forced
+ *     `--runner nrfjprog` for every non-ESP32 target, which broke boards whose
+ *     default is not nrfjprog (xiao_ble defaults to nrfutil) and required
+ *     Nordic J-Link tools that a USB-bootloader board does not have.
+ *
+ * Exported (pure) so the runner-selection contract is unit-testable without
+ * spawning west.
+ */
+export function buildFlashArgs(buildDir, board, userRunner, port) {
+    const args = ['flash', '-d', buildDir];
+    if (userRunner) {
+        args.push('--runner', userRunner);
+    }
+    if (port && board.startsWith('esp32')) {
+        args.push('--esp-device', port);
+    }
+    return args;
+}
+/**
+ * Classify a `west flash` result as success/failure.
+ *
+ * west's exit status is authoritative except for one known race in the uf2
+ * runner on Windows: the UF2 bootloader reboots to run new firmware the instant
+ * the file copy completes, unmounting the USB-MSC drive before `shutil.copy`'s
+ * trailing `copymode`/chmod runs. That raises `OSError: [WinError 433] A
+ * device which does not exist was specified` and makes west exit non-zero —
+ * even though the firmware copied and flashed correctly (the LED blinks).
+ *
+ * The copy starting is logged ("Copying UF2 file to '<drive>'"); WinError 433
+ * during `copymode` after that point proves the data write finished and the
+ * drive only vanished on the metadata step. Treat that exact signature as
+ * success so the upload isn't reported as a failure. Genuine uf2 failures
+ * (no partition found, write errors before the copy) still surface as failures.
+ *
+ * Exported (pure) so the classification is unit-testable without spawning west.
+ */
+export function classifyUploadResult(runner, status, output) {
+    if (status === 0)
+        return true;
+    if (isUf2DriveVanishRace(output))
+        return runner === 'uf2';
+    return false;
+}
+/**
+ * Whether `output` carries the benign UF2 copymode/WinError-433 race signature
+ * (see classifyUploadResult). Centralized so classify + cleanse share one match.
+ */
+function isUf2DriveVanishRace(output) {
+    return /Copying UF2 file to/.test(output)
+        && /WinError 433/.test(output)
+        && /copymode/.test(output);
+}
+/**
+ * Cleanse the `west flash` output shown to the user.
+ *
+ * When classifyUploadResult has decided a non-zero west exit was the benign UF2
+ * race (firmware copied, drive unmounted on the trailing chmod), the raw output
+ * is a wall of Python traceback that reads like a hard failure. Drop everything
+ * after the "Copying UF2 file to" line — i.e. the entire traceback — so a
+ * successful flash reads as a success (the framework's ✓ Done follows). Non-race
+ * output is returned untouched; genuine errors stay fully visible for diagnosis.
+ *
+ * Exported (pure) so the cleansing is unit-testable without spawning west.
+ */
+export function cleanseUploadOutput(runner, status, output) {
+    if (status === 0)
+        return output;
+    if (runner === 'uf2' && isUf2DriveVanishRace(output)) {
+        // Keep everything west printed up to and including "Copying UF2 file to",
+        // then stop — everything after that is the drive-vanish traceback.
+        const upto = output.match(/[\s\S]*Copying UF2 file to[^\n]*/);
+        const head = upto ? upto[0] : '-- west flash: using runner uf2';
+        return head;
+    }
+    return output;
+}
+/**
+ * FrameworkToolchain for Zephyr. Spec §3.5 (mirror of the ESP-IDF toolchain).
+ * The target board is carried via frameworkData.buildTarget; scaffolding
+ * happens at compile time when the target is known.
+ */
+export const Toolchain = {
+    prepare(outputDir, entryPoint) {
+        // Write the DT overlay for the default board (the real target is known at
+        // compile time; prepare runs before compile, so use the default board id).
+        // The overlay is additive and idempotent; compile re-runs prepare-equivalent
+        // logic in scaffold via the usage scan. Mirrors how Arduino's library
+        // resolution is a pre-build artifact step.
+        const projectRoot = basename(outputDir) === 'src' ? dirname(outputDir) : outputDir;
+        const board = DEFAULT_BOARD;
+        const chip = chipForTarget(board);
+        // Scan the emitted source for usage tokens (same authoritative signal the
+        // scaffold uses). entryPoint is the path to main.cpp; its dir is src/.
+        const srcDir = dirname(entryPoint);
+        let src = '';
+        try {
+            for (const name of readdirSync(srcDir)) {
+                if (name.endsWith('.cpp') || name.endsWith('.c')) {
+                    src += readFileSync(join(srcDir, name), 'utf8');
+                }
+            }
+        }
+        catch { /* src may not exist yet on first prepare */ }
+        const uses = (t) => src.includes(t);
+        // Display usage tokens: the minimal GFX runtime (display_write/_fill_rect)
+        // and the UI display adapter (display_init / __tc_display_dev /
+        // DEVICE_DT_GET on the display nodelabel). Both paths need the DT overlay
+        // to enable the display node.
+        const usesDisplay = uses('display_write') || uses('display_init')
+            || uses('display_fill_rect') || uses('__tc_display_dev')
+            || uses('CuttlefishDisplayTarget');
+        // Both registered Zephyr display profiles use dtLabel 'display0', so the
+        // default profile's overlay block (&display0 { status="okay" }) is correct
+        // for either driver. Thread a non-default profile here only if a future
+        // board carries a display node under a different nodelabel.
+        const displayProfile = usesDisplay ? DEFAULT_ZEPHYR_DISPLAY_PROFILE : undefined;
+        const overlay = generateOverlay(chip, {
+            usesI2c: uses('i2c_'),
+            usesSpi: uses('spi_'),
+            usesUart: uses('uart_'),
+            usesDisplay,
+            usesTouch: uses('ft6336u') || uses('touch_'),
+        }, displayProfile);
+        const overlayDir = join(projectRoot, 'boards');
+        mkdirSync(overlayDir, { recursive: true });
+        writeIfChanged(join(overlayDir, `${board}.overlay`), overlay);
+    },
+    compile(o) {
+        const projectRoot = projectRootFromOptions(o);
+        const board = targetFromOptions(o);
+        const debugMode = new ZephyrStrategy().debugMode(board);
+        const isGdbDebug = o.debug === true && debugMode === 'gdb';
+        const zc = o.zephyrConfig;
+        const userKconfig = zc?.kconfig;
+        const configChanged = scaffoldZephyrProject(projectRoot, isGdbDebug, userKconfig, o.psram);
+        // Regenerate the DT overlay for the ACTUAL target board. prepare() writes
+        // it for the default board (the real target is unknown until compile), so
+        // the <default>.overlay it wrote does not match `west build -b <board>`.
+        // Zephyr auto-detects boards/<board>.overlay under APPLICATION_CONFIG_DIR.
+        try {
+            const chip = chipForTarget(board);
+            const srcDir = join(projectRoot, 'src');
+            let src = '';
+            try {
+                for (const name of readdirSync(srcDir)) {
+                    if (name.endsWith('.cpp') || name.endsWith('.c')) {
+                        src += readFileSync(join(srcDir, name), 'utf-8');
+                    }
+                }
+            }
+            catch { /* src may not exist */ }
+            const uses = (t) => src.includes(t);
+            const usesDisplay = uses('display_write') || uses('display_init')
+                || uses('display_fill_rect') || uses('__tc_display_dev')
+                || uses('CuttlefishDisplayTarget');
+            // Derive the display dimensions from the emitted adapter code
+            // (display_width/height return the profile's w/h). This ensures the DT
+            // overlay's width/height match the panel the adapter targets, not the
+            // default profile — critical for drivers like ST7796S that initialize
+            // the panel geometry from the DT node.
+            let displayProfile = usesDisplay ? DEFAULT_ZEPHYR_DISPLAY_PROFILE : undefined;
+            if (usesDisplay) {
+                const wMatch = src.match(/display_width\(\)\s*\{\s*return\s+(\d+)\s*;\s*\}/);
+                const hMatch = src.match(/display_height\(\)\s*\{\s*return\s+(\d+)\s*;\s*\}/);
+                if (wMatch && hMatch) {
+                    displayProfile = {
+                        ...DEFAULT_ZEPHYR_DISPLAY_PROFILE,
+                        width: parseInt(wMatch[1], 10),
+                        height: parseInt(hMatch[1], 10),
+                    };
+                }
+            }
+            // Extract display pin wiring (cs/dc/rst/spiFrequency/spiPins) from the
+            // config display section so the DT overlay wires the MIPI DBI bridge to
+            // the correct GPIOs + SPI bus pins.
+            const dispCfg = o.display;
+            const spiPins = (dispCfg?.spiPins ?? undefined);
+            const wiring = dispCfg
+                ? {
+                    cs: typeof dispCfg.cs === 'number' ? dispCfg.cs : undefined,
+                    dc: typeof dispCfg.dc === 'number' ? dispCfg.dc : undefined,
+                    rst: typeof dispCfg.rst === 'number' ? dispCfg.rst : undefined,
+                    spiFrequency: typeof dispCfg.spiFrequency === 'number' ? dispCfg.spiFrequency : undefined,
+                    sck: typeof spiPins?.sck === 'number' ? spiPins.sck : undefined,
+                    mosi: typeof spiPins?.mosi === 'number' ? spiPins.mosi : undefined,
+                    miso: typeof spiPins?.miso === 'number' ? spiPins.miso : undefined,
+                    backlightPin: typeof dispCfg.backlightPin === 'number' ? dispCfg.backlightPin : undefined,
+                }
+                : undefined;
+            // Extract touch pin wiring (irq/resetPin/sda/scl) from the config
+            // display.touch section so the DT overlay wires the I2C bus + touch node.
+            const touchCfg = dispCfg?.touch;
+            const touchWiring = touchCfg
+                ? {
+                    irq: typeof touchCfg.irq === 'number' ? touchCfg.irq : undefined,
+                    resetPin: typeof touchCfg.resetPin === 'number' ? touchCfg.resetPin : undefined,
+                    sda: typeof touchCfg.sda === 'number' ? touchCfg.sda : undefined,
+                    scl: typeof touchCfg.scl === 'number' ? touchCfg.scl : undefined,
+                }
+                : undefined;
+            const overlay = generateOverlay(chip, {
+                usesI2c: uses('i2c_'),
+                usesSpi: uses('spi_'),
+                usesUart: uses('uart_'),
+                usesDisplay,
+                usesTouch: uses('ft6336u') || uses('touch_'),
+                psram: o.psram,
+            }, displayProfile, wiring, touchWiring);
+            const overlayDir = join(projectRoot, 'boards');
+            mkdirSync(overlayDir, { recursive: true });
+            // Write the board-specific overlay (the one west loads). Zephyr looks for
+            // boards/<board_id>.overlay under APPLICATION_CONFIG_DIR — use the bare
+            // board id (before any hardware-qualifier suffix, e.g. 'esp32_devkitc'
+            // not the full 'esp32_devkitc/esp32/procpu' target string).
+            const boardId = board.split('/')[0];
+            writeIfChanged(join(overlayDir, `${boardId}.overlay`), overlay);
+        }
+        catch { /* best-effort overlay regen; the build surfaces DT errors */ }
+        // Use a stable build dir so incremental builds reuse the Ninja graph.
+        // west defaults to <projectRoot>/build.
+        const buildDir = join(projectRoot, 'build');
+        // Nuke the build dir whenever a previous build exists. Zephyr's gen_offset
+        // flow (offsets.h is generated FROM offsets.c.obj, while gen_offset.h makes
+        // offsets.c include offsets.h) leaves a permanent `offsets.h ->
+        // offsets.c.obj -> offsets.h` cycle in the .ninja_deps log after the first
+        // incremental pass — ninja then fails every later build with `dependency
+        // cycle` even when nothing changed. This is a known Zephyr-on-Windows
+        // issue; the reliable fix is a pristine build dir per build. Also nukes
+        // when prj.conf/CMakeLists/overlay changed, so Kconfig symbols and
+        // generated headers never diverge from a cached graph.
+        if (configChanged || existsSync(join(buildDir, 'zephyr', 'zephyr.bin'))) {
+            try {
+                rmSync(buildDir, { recursive: true, force: true });
+            }
+            catch { /* may not exist */ }
+        }
+        const buildArgs = ['build', '-b', board, '-d', buildDir, projectRoot];
+        // Explicitly pass the generated DT overlay. Zephyr's auto-detection of
+        // boards/<board>.overlay fails for hardware-qualified targets (e.g.
+        // esp32_devkitc/esp32/procpu) because the FILE_SUFFIX matching doesn't
+        // resolve — passing -DDTC_OVERLAY_FILE forces it unconditionally.
+        const boardId = board.split('/')[0];
+        const overlayPath = join(projectRoot, 'boards', `${boardId}.overlay`);
+        try {
+            if (readFileSync(overlayPath, 'utf-8').length > 0) {
+                // CMake parses backslashes as escapes — use forward slashes so the
+                // Windows path survives the -D argument intact.
+                buildArgs.push('--', `-DDTC_OVERLAY_FILE=${overlayPath.replace(/\\/g, '/')}`);
+            }
+        }
+        catch { /* no overlay — let Zephyr auto-detect or build without one */ }
+        // Append user cmake args from cuttlefish.config.ts zephyr.cmakeArgs.
+        const userCmakeArgs = zc?.cmakeArgs;
+        if (userCmakeArgs && userCmakeArgs.length > 0) {
+            if (!buildArgs.includes('--'))
+                buildArgs.push('--');
+            buildArgs.push(...userCmakeArgs);
+        }
+        const inv = westSpawn(buildArgs, { cwd: projectRoot, encoding: 'utf-8', timeout: BUILD_TIMEOUT_MS });
+        const result = spawnSync(inv.command, inv.args, inv.options);
+        const stdout = typeof result.stdout === 'string' ? result.stdout : (result.stdout?.toString() ?? '');
+        const stderr = typeof result.stderr === 'string' ? result.stderr : (result.stderr?.toString() ?? '');
+        const output = stdout + stderr;
+        // Prefix the build log with how west was resolved, for transparency.
+        const header = `Using west via ${inv.install.source}` +
+            (inv.install.zephyrBase ? ` (ZEPHYR_BASE=${inv.install.zephyrBase})` : '') + '\n';
+        // After a successful build in gdb mode (--debug on a probe-capable target),
+        // write the VS Code launch.json + tasks.json + gdb-script artifacts so F5
+        // attaches GDB to the chip's debug probe. Non-fatal on failure — a missing
+        // artifact doesn't block the build. Mirrors the deleted framework-esp32
+        // toolchain compile() debug-config wiring.
+        if (result.status === 0 && isGdbDebug) {
+            try {
+                const { workspaceRoot, sketchRel } = resolveDebugLocations(projectRoot);
+                writeDebugConfig({
+                    projectRoot,
+                    workspaceRoot,
+                    sketchRel,
+                    target: board,
+                    buildDir,
+                    sourceMapPath: join(dirname(o.sourcePath), `${basename(o.sourcePath)}.thcppmap.json`),
+                });
+            }
+            catch (e) {
+                console.warn(`[cuttlefish] gdb debug config generation failed: ${e.message}`);
+            }
+        }
+        return {
+            success: result.status === 0,
+            output: header + output,
+            errors: parseCompileErrors(output, o.sourcePath),
+        };
+    },
+    upload(o) {
+        const projectRoot = projectRootFromOptions(o);
+        const buildDir = join(projectRoot, 'build');
+        const board = targetFromOptions(o);
+        const zc = o.zephyrConfig;
+        const runner = zc?.runner;
+        const args = buildFlashArgs(buildDir, board, runner, o.port);
+        const inv = westSpawn(args, {
+            cwd: projectRoot,
+            encoding: 'utf-8',
+            timeout: FLASH_TIMEOUT_MS,
+        });
+        const result = spawnSync(inv.command, inv.args, inv.options);
+        const fstdout = typeof result.stdout === 'string' ? result.stdout : (result.stdout?.toString() ?? '');
+        const fstderr = typeof result.stderr === 'string' ? result.stderr : (result.stderr?.toString() ?? '');
+        const raw = fstdout + fstderr;
+        return {
+            success: classifyUploadResult(runner, result.status, raw),
+            output: cleanseUploadOutput(runner, result.status, raw),
+        };
+    },
+    monitor(o) {
+        // Serial monitor over USB-CDC. Zephyr does NOT ship a `west serial`
+        // subcommand (it's not a real west command — invoking it errors with
+        // "unknown command"). The discovered west install's venv carries pyserial,
+        // so run its bundled miniterm directly: `python -m serial.tools.miniterm`.
+        // That is the same cross-platform terminal pyserial provides in ESP-IDF's
+        // idf.py monitor, and it inherits stdio so Ctrl+C exits cleanly.
+        if (!o.port) {
+            throw new Error('A serial port is required to monitor. Pass --port <COMx/ttyX>.');
+        }
+        // ESP32 USB-CDC console runs at 115200 (the Zephyr ESP32 board default).
+        // The CLI's generic default of 9600 is wrong for this target; honor an
+        // explicit --baud / config.console.baudRate when given, else 115200.
+        const baud = o.baud ?? 115200;
+        const install = discoverWest();
+        const py = install?.pythonExecutable ?? process.env.PYTHON ?? 'python';
+        // Reuse west-spawn's env builder (prepends the venv bin dir to PATH so the
+        // python we spawn resolves pyserial from the same venv). Falls back to the
+        // process env when no install is discovered.
+        const env = install ? buildEnv(install) : process.env;
+        spawnSync(py, ['-m', 'serial.tools.miniterm', o.port, String(baud)], {
+            cwd: projectRootFromOptions(o),
+            env,
+            stdio: 'inherit',
+        });
+    },
+    debug(o) {
+        // Launch an interactive GDB session for the last build. `west debug`
+        // auto-resolves the runner (openocd for esp32s3, nrfjprog/jlink for nRF)
+        // and the GDB binary from the build dir's CMakeCache/board.cmake — no
+        // hand-authored gdbinit needed. Inherits stdio so GDB runs interactively.
+        // (Not invoked by the standard build/compile flow; powers an explicit
+        // debug-attach entry point for terminal-driven debugging without VS Code.)
+        const projectRoot = projectRootFromOptions(o);
+        const buildDir = join(projectRoot, 'build');
+        const inv = westSpawn(['debug', '-d', buildDir], {
+            cwd: projectRoot,
+            encoding: 'utf-8',
+            stdio: 'inherit',
+        });
+        spawnSync(inv.command, inv.args, inv.options);
+    },
+};

package/dist/toolchain/scaffold.d.ts

@@ -0,0 +1,15 @@
+/** 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 declare function writeIfChanged(filePath: string, content: string): boolean;
+/**
+ * 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 declare function scaffoldZephyrProject(projectRoot: string, debug?: boolean, userKconfig?: Record<string, string>, psram?: 'opi' | 'quad'): boolean;

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;
+}