@typecad/framework-zephyr 1.0.0-alpha.11 → 1.0.0-alpha.13

package/dist/toolchain/debug-config.d.ts

@@ -13,8 +13,10 @@ export interface DebugConfigOptions {
     sourceMapPath?: string;
 }
 /**
- * Resolve the GDB binary path for the target from the build cache. Zephyr
- * records ZEPHYR_SDK_INSTALL_DIR in CMakeCache.txt at configure time, and the
+ * Resolve the GDB binary path for the target from the build cache, falling
+ * back to a filesystem scan of known Zephyr SDK locations when no build
+ * exists yet (the create-time starter artifacts path). Zephyr records
+ * ZEPHYR_SDK_INSTALL_DIR in CMakeCache.txt at configure time, and the
  * xtensa GDB lives at <sdk>/xtensa-espressif_esp32s3_zephyr-elf/bin/... (note
  * the Zephyr-SDK naming, distinct from the ESP-IDF xtensa-esp32s3-elf-gdb).
  *
@@ -22,6 +24,24 @@ export interface DebugConfigOptions {
  * omits gdbPath and relies on Cortex-Debug's default resolution).
  */
 export declare function resolveGdbPath(buildDir: string, target: string): string | undefined;
+/** The esp32s3 xtensa GDB location inside a Zephyr SDK root (verified against
+ *  zephyr-sdk-0.17.4). Returns a forward-slash absolute path or undefined. */
+export declare function gdbPathFromSdkRoot(sdkRoot: string): string | undefined;
+/**
+ * Probe the well-known Zephyr SDK install locations, newest version first:
+ *   1. $ZEPHYR_SDK_INSTALL_DIR (the var board.cmake reads)
+ *   2. <MAMBA_ROOT_PREFIX | ~/micromamba>/zephyr-sdk/zephyr-sdk-<ver> — the
+ *      @typecad/zephyr-installer layout
+ *   3. ~/zephyr-sdk-<ver> — the standalone download layout
+ *
+ * Only roots that actually contain the esp32s3 GDB are useful to callers;
+ * this returns candidate roots (gdbPathFromSdkRoot does the existence check)
+ * so tests can inject home/env overrides.
+ */
+export declare function discoverZephyrSdkRoots(opts?: {
+    home?: string;
+    env?: Record<string, string | undefined>;
+}): string[];
 /**
  * Resolve the Espressif OpenOCD binary path. The esp32s3 needs the Espressif
  * OpenOCD fork (openocd-esp32) — not the Zephyr SDK's openocd and not a
@@ -80,3 +100,24 @@ export declare function generateGdbScript(sourceMapPath?: string): string | null
  *   <projectRoot>/.cuttlefish/.cuttlefish-gdb.py  (lambda frame filter, conditional)
  */
 export declare function writeDebugConfig(o: DebugConfigOptions): void;
+/**
+ * Create-time starter debug artifacts. Called by the cuttlefish `create` flow
+ * (via the package's `writeProjectDebugArtifacts` export) so a fresh project
+ * has a working F5 before any build exists:
+ *
+ * The launch.json's preLaunchTask runs `cuttlefish build --compile --upload
+ * --debug`, which builds + flashes AND rewrites this same launch entry (merged
+ * by name) with the CMakeCache-resolved gdbPath — so the starter files upgrade
+ * themselves on the first debug build.
+ *
+ * No-ops (returns []) for targets without native GDB support (debugMode() !==
+ * 'gdb'); the gdb frame-filter script is skipped (no source map exists yet).
+ *
+ * Returns the workspace-relative paths written, for CLI reporting.
+ */
+export declare function writeProjectDebugArtifacts(o: {
+    /** Absolute path to the cuttlefish project root (contains cuttlefish.config.ts). */
+    workspaceRoot: string;
+    /** The Zephyr board id from the project config (frameworkData.buildTarget). */
+    buildTarget?: string;
+}): string[];

package/dist/toolchain/debug-config.js

@@ -16,9 +16,12 @@
 // ---------------------------------------------------------------------------
 import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync } from 'node:fs';
 import { join, resolve, dirname, relative } from 'node:path';
+import { ZephyrStrategy } from '../strategy.js';
 /**
- * Resolve the GDB binary path for the target from the build cache. Zephyr
- * records ZEPHYR_SDK_INSTALL_DIR in CMakeCache.txt at configure time, and the
+ * Resolve the GDB binary path for the target from the build cache, falling
+ * back to a filesystem scan of known Zephyr SDK locations when no build
+ * exists yet (the create-time starter artifacts path). Zephyr records
+ * ZEPHYR_SDK_INSTALL_DIR in CMakeCache.txt at configure time, and the
  * xtensa GDB lives at <sdk>/xtensa-espressif_esp32s3_zephyr-elf/bin/... (note
  * the Zephyr-SDK naming, distinct from the ESP-IDF xtensa-esp32s3-elf-gdb).
  *
@@ -26,27 +29,92 @@ import { join, resolve, dirname, relative } from 'node:path';
  * omits gdbPath and relies on Cortex-Debug's default resolution).
  */
 export function resolveGdbPath(buildDir, target) {
+    void target; // toolchain dir is esp32s3-specific today; see gdbPathFromSdkRoot
     const cachePath = join(buildDir, 'CMakeCache.txt');
-    if (!existsSync(cachePath))
-        return undefined;
-    let sdk = '';
-    try {
-        const cache = readFileSync(cachePath, 'utf-8');
-        const m = cache.match(/^ZEPHYR_SDK_INSTALL_DIR:PATH=(.+)$/m);
-        if (m)
-            sdk = m[1].trim();
+    if (existsSync(cachePath)) {
+        try {
+            const cache = readFileSync(cachePath, 'utf-8');
+            const m = cache.match(/^ZEPHYR_SDK_INSTALL_DIR:PATH=(.+)$/m);
+            if (m) {
+                const fromCache = gdbPathFromSdkRoot(m[1].trim());
+                if (fromCache)
+                    return fromCache;
+            }
+        }
+        catch {
+            // unreadable cache — fall through to the SDK scan
+        }
     }
-    catch {
-        return undefined;
+    // No build dir yet (project just created): probe known SDK locations.
+    for (const sdkRoot of discoverZephyrSdkRoots()) {
+        const p = gdbPathFromSdkRoot(sdkRoot);
+        if (p)
+            return p;
     }
-    if (!sdk)
-        return undefined;
-    // The Zephyr SDK toolchain dir is target-specific. For esp32s3 it is
-    // xtensa-espressif_esp32s3_zephyr-elf (verified against zephyr-sdk-0.17.4).
+    return undefined;
+}
+/** The esp32s3 xtensa GDB location inside a Zephyr SDK root (verified against
+ *  zephyr-sdk-0.17.4). Returns a forward-slash absolute path or undefined. */
+export function gdbPathFromSdkRoot(sdkRoot) {
     const gdbName = 'xtensa-espressif_esp32s3_zephyr-elf-gdb.exe';
-    const gdbPath = join(sdk, 'xtensa-espressif_esp32s3_zephyr-elf', 'bin', gdbName);
+    const gdbPath = join(sdkRoot, 'xtensa-espressif_esp32s3_zephyr-elf', 'bin', gdbName);
     return existsSync(gdbPath) ? gdbPath.replace(/\\/g, '/') : undefined;
 }
+/** Compare two dotted version strings numerically (0.17.10 > 0.17.4). */
+function compareSdkVersions(a, b) {
+    const segsOf = (v) => v.split('.').map((s) => parseInt(s, 10) || 0);
+    const aa = segsOf(a);
+    const bb = segsOf(b);
+    for (let i = 0; i < Math.max(aa.length, bb.length); i++) {
+        const d = (aa[i] ?? 0) - (bb[i] ?? 0);
+        if (d !== 0)
+            return d;
+    }
+    return 0;
+}
+/**
+ * Probe the well-known Zephyr SDK install locations, newest version first:
+ *   1. $ZEPHYR_SDK_INSTALL_DIR (the var board.cmake reads)
+ *   2. <MAMBA_ROOT_PREFIX | ~/micromamba>/zephyr-sdk/zephyr-sdk-<ver> — the
+ *      @typecad/zephyr-installer layout
+ *   3. ~/zephyr-sdk-<ver> — the standalone download layout
+ *
+ * Only roots that actually contain the esp32s3 GDB are useful to callers;
+ * this returns candidate roots (gdbPathFromSdkRoot does the existence check)
+ * so tests can inject home/env overrides.
+ */
+export function discoverZephyrSdkRoots(opts) {
+    const env = opts?.env ?? process.env;
+    const home = opts?.home ?? (env.USERPROFILE || env.HOME || '');
+    const scanned = [];
+    const versionedDirs = (base) => {
+        try {
+            return readdirSync(base)
+                .filter((d) => existsSync(join(base, d)) && d.startsWith('zephyr-sdk-'))
+                .map((d) => join(base, d));
+        }
+        catch {
+            return []; // dir absent
+        }
+    };
+    const mambaRoot = env.MAMBA_ROOT_PREFIX || (home ? join(home, 'micromamba') : '');
+    if (mambaRoot)
+        scanned.push(...versionedDirs(join(mambaRoot, 'zephyr-sdk')));
+    if (home)
+        scanned.push(...versionedDirs(home));
+    // Scanned roots newest version first; the env var stays pinned first
+    // (explicit user intent outranks any discovered location).
+    scanned.sort((a, b) => {
+        const va = a.match(/zephyr-sdk-([\d.]+)/)?.[1] ?? '';
+        const vb = b.match(/zephyr-sdk-([\d.]+)/)?.[1] ?? '';
+        return compareSdkVersions(vb, va);
+    });
+    const roots = env.ZEPHYR_SDK_INSTALL_DIR
+        ? [env.ZEPHYR_SDK_INSTALL_DIR, ...scanned]
+        : scanned;
+    // De-duplicate (an env var may repeat a scan hit) preserving order.
+    return roots.filter((r, i) => roots.indexOf(r) === i);
+}
 /**
  * Resolve the Espressif OpenOCD binary path. The esp32s3 needs the Espressif
  * OpenOCD fork (openocd-esp32) — not the Zephyr SDK's openocd and not a
@@ -357,3 +425,47 @@ export function writeDebugConfig(o) {
     const task = buildTask(o);
     mergeJsonArrayEntry(join(vscodeDir, 'tasks.json'), 'tasks', 'label', task);
 }
+/**
+ * The Zephyr app dir a `cuttlefish create` scaffold produces, relative to the
+ * project root: the scaffold fixes entry `./src/main.ts` + outDir `./out`, and
+ * the CLI resolves output.outDir against the ENTRY's directory (cli.ts), so
+ * the emitted app root — and therefore the ELF, build dir, and .cuttlefish/
+ * debug artifacts — always lands at `src/out`. Keep in sync with
+ * generateProjectConfig in @typecad/cuttlefish create/init-templates.ts.
+ */
+const STARTER_SKETCH_REL = 'src/out';
+/**
+ * Create-time starter debug artifacts. Called by the cuttlefish `create` flow
+ * (via the package's `writeProjectDebugArtifacts` export) so a fresh project
+ * has a working F5 before any build exists:
+ *
+ * The launch.json's preLaunchTask runs `cuttlefish build --compile --upload
+ * --debug`, which builds + flashes AND rewrites this same launch entry (merged
+ * by name) with the CMakeCache-resolved gdbPath — so the starter files upgrade
+ * themselves on the first debug build.
+ *
+ * No-ops (returns []) for targets without native GDB support (debugMode() !==
+ * 'gdb'); the gdb frame-filter script is skipped (no source map exists yet).
+ *
+ * Returns the workspace-relative paths written, for CLI reporting.
+ */
+export function writeProjectDebugArtifacts(o) {
+    if (new ZephyrStrategy().debugMode(o.buildTarget) !== 'gdb')
+        return [];
+    const workspaceRoot = resolve(o.workspaceRoot);
+    const projectRoot = join(workspaceRoot, STARTER_SKETCH_REL);
+    writeDebugConfig({
+        projectRoot,
+        workspaceRoot,
+        sketchRel: STARTER_SKETCH_REL,
+        target: o.buildTarget ?? '',
+        // No build dir exists yet — resolveGdbPath falls back to probing known
+        // Zephyr SDK locations so gdbPath is still filled in when possible.
+        buildDir: join(projectRoot, 'build'),
+    });
+    return [
+        '.vscode/launch.json',
+        '.vscode/tasks.json',
+        `${STARTER_SKETCH_REL}/.cuttlefish/openocd.cfg`,
+    ];
+}

package/dist/toolchain/index.d.ts

@@ -59,6 +59,19 @@ export declare function classifyUploadResult(runner: string | undefined, status:
  * Exported (pure) so the cleansing is unit-testable without spawning west.
  */
 export declare function cleanseUploadOutput(runner: string | undefined, status: number | null, output: string): string;
+/**
+ * Whether a failed `west build` output carries ninja's `dependency cycle`
+ * signature. Zephyr 4.3.99-dev snapshots have a regression
+ * (zephyrproject-rtos/zephyr#104757, fixed upstream by the #104784 revert,
+ * in v4.4+): after CMake re-runs from a .config change, the build dir's
+ * .ninja_deps records an `offsets.h -> offsets.c.obj -> offsets.h` cycle and
+ * ninja aborts with `ninja: error: dependency cycle: ...` before compiling
+ * anything. The cycle lives in the build dir, not the sources, so compile()
+ * recovers by deleting the dir and retrying once.
+ *
+ * Exported (pure) so the detection is unit-testable without spawning west.
+ */
+export declare function isDependencyCycleFailure(output: string): boolean;
 /**
  * FrameworkToolchain for Zephyr. Spec §3.5 (mirror of the ESP-IDF toolchain).
  * The target board is carried via frameworkData.buildTarget; scaffolding

package/dist/toolchain/index.js

@@ -19,7 +19,7 @@
 // ---------------------------------------------------------------------------
 import { spawnSync } from 'node:child_process';
 import { basename, dirname, join } from 'node:path';
-import { readdirSync, readFileSync, mkdirSync, rmSync, existsSync } from 'node:fs';
+import { readdirSync, readFileSync, mkdirSync, rmSync } from 'node:fs';
 import { parseCompileErrors } from '@typecad/cuttlefish/api/shared';
 import { scaffoldZephyrProject, writeIfChanged } from './scaffold.js';
 import { westSpawn, buildEnv } from './west-spawn.js';
@@ -145,6 +145,29 @@ export function cleanseUploadOutput(runner, status, output) {
     }
     return output;
 }
+/**
+ * Whether a failed `west build` output carries ninja's `dependency cycle`
+ * signature. Zephyr 4.3.99-dev snapshots have a regression
+ * (zephyrproject-rtos/zephyr#104757, fixed upstream by the #104784 revert,
+ * in v4.4+): after CMake re-runs from a .config change, the build dir's
+ * .ninja_deps records an `offsets.h -> offsets.c.obj -> offsets.h` cycle and
+ * ninja aborts with `ninja: error: dependency cycle: ...` before compiling
+ * anything. The cycle lives in the build dir, not the sources, so compile()
+ * recovers by deleting the dir and retrying once.
+ *
+ * Exported (pure) so the detection is unit-testable without spawning west.
+ */
+export function isDependencyCycleFailure(output) {
+    return output.includes('dependency cycle');
+}
+/** stdout+stderr of a spawnSync result coerced to one string. Defensive about
+ *  the buffer form (spawnSync only returns strings when `encoding` is set,
+ *  which every call site here does — but the coercion costs nothing). */
+function combinedSpawnOutput(result) {
+    const so = typeof result.stdout === 'string' ? result.stdout : (result.stdout?.toString() ?? '');
+    const se = typeof result.stderr === 'string' ? result.stderr : (result.stderr?.toString() ?? '');
+    return so + se;
+}
 /**
  * FrameworkToolchain for Zephyr. Spec §3.5 (mirror of the ESP-IDF toolchain).
  * The target board is carried via frameworkData.buildTarget; scaffolding
@@ -185,12 +208,17 @@ export const Toolchain = {
         // 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;
+        // Touch controller kind comes from which DT nodelabel the emitted adapter
+        // references (FT6336U on I2C, XPT2046 on the display's SPI bus).
+        const usesTouch = uses('ft6336u') || uses('touch_');
+        const usesXpt = uses('xpt2046');
         const overlay = generateOverlay(chip, {
             usesI2c: uses('i2c_'),
             usesSpi: uses('spi_'),
             usesUart: uses('uart_'),
             usesDisplay,
-            usesTouch: uses('ft6336u') || uses('touch_'),
+            usesTouch: usesTouch || usesXpt,
+            touchController: usesXpt ? 'xpt2046' : 'ft6336u',
         }, displayProfile);
         const overlayDir = join(projectRoot, 'boards');
         mkdirSync(overlayDir, { recursive: true });
@@ -272,27 +300,57 @@ export const Toolchain = {
                     mosi: typeof spiPins?.mosi === 'number' ? spiPins.mosi : undefined,
                     miso: typeof spiPins?.miso === 'number' ? spiPins.miso : undefined,
                     backlightPin: typeof dispCfg.backlightPin === 'number' ? dispCfg.backlightPin : undefined,
+                    tearingEffectPin: typeof dispCfg.tearingEffectPin === 'number' ? dispCfg.tearingEffectPin : 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.
+            // Extract touch pin wiring from the config display.touch section so the
+            // DT overlay wires the bus + touch node. I2C (FT6336U) carries
+            // irq/resetPin/sda/scl; SPI (XPT2046) carries irq/cs + the calibration
+            // range the xptek,xpt2046 binding requires.
             const touchCfg = dispCfg?.touch;
-            const touchWiring = touchCfg
+            const isXpt = touchCfg?.library === 'XPT2046_Touchscreen';
+            const touchCal = touchCfg?.calibration;
+            const num = (v) => (typeof v === 'number' ? v : undefined);
+            let 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,
+                    controller: isXpt ? 'xpt2046' : 'ft6336u',
+                    irq: num(touchCfg.irq),
+                    resetPin: num(touchCfg.resetPin),
+                    sda: num(touchCfg.sda),
+                    scl: num(touchCfg.scl),
+                    cs: num(touchCfg.cs),
+                    calibration: touchCal
+                        ? {
+                            xMin: num(touchCal.xMin) ?? 0,
+                            xMax: num(touchCal.xMax) ?? 4095,
+                            yMin: num(touchCal.yMin) ?? 0,
+                            yMax: num(touchCal.yMax) ?? 4095,
+                        }
+                        : undefined,
+                    minPressure: num(touchCfg.minPressure),
                 }
                 : undefined;
+            // Touch controller kind for Kconfig (bus driver selection) and the DT
+            // node shape: from the config when available, else from the DT nodelabel
+            // the emitted adapter references. Forced onto touchWiring so a source
+            // scan match without a config section still emits the right node.
+            const usesXpt = isXpt || uses('xpt2046');
+            if (usesXpt) {
+                touchWiring = { controller: 'xpt2046', ...(touchWiring ?? {}) };
+            }
+            const overlayDiagnostics = [];
             const overlay = generateOverlay(chip, {
                 usesI2c: uses('i2c_'),
                 usesSpi: uses('spi_'),
                 usesUart: uses('uart_'),
                 usesDisplay,
-                usesTouch: uses('ft6336u') || uses('touch_'),
+                usesTouch: uses('ft6336u') || uses('touch_') || usesXpt,
+                touchController: usesXpt ? 'xpt2046' : 'ft6336u',
                 psram: o.psram,
-            }, displayProfile, wiring, touchWiring);
+            }, displayProfile, wiring, touchWiring, overlayDiagnostics);
+            for (const d of overlayDiagnostics) {
+                console.warn(`overlay: ${d.message}`);
+            }
             const overlayDir = join(projectRoot, 'boards');
             mkdirSync(overlayDir, { recursive: true });
             // Write the board-specific overlay (the one west loads). Zephyr looks for
@@ -306,16 +364,23 @@ export const Toolchain = {
         // 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'))) {
+        // Reuse the build dir across builds so ninja recompiles only the changed
+        // app translation units and re-links — a pristine configure + the
+        // ~280-target Zephyr library rebuild costs minutes on Windows
+        // (demo-shadcn measures 69s of ninja wall time, 448s of summed compile
+        // work, and every build redid all of it). Nuke it only when the generated
+        // config changed (prj.conf / CMakeLists content), the one path that must
+        // not reuse a cached graph: Zephyr 4.3.99-dev snapshots carry a
+        // regression (zephyrproject-rtos/zephyr#104757, fixed by the #104784
+        // revert on 2026-03-03, in v4.4+) where re-running CMake after a .config
+        // change records an `offsets.h -> offsets.c.obj -> offsets.h` cycle in
+        // .ninja_deps, after which every ninja run fails with `dependency cycle`.
+        // Plain source edits never reconfigure CMake, so they cannot trigger it —
+        // and the retry after the spawn below self-heals any path that still does.
+        // Board switches need no nuke here: `west build` is --pristine=auto by
+        // default and recreates the dir itself when -b <board> mismatches the
+        // cached board.
+        if (configChanged) {
             try {
                 rmSync(buildDir, { recursive: true, force: true });
             }
@@ -344,10 +409,26 @@ export const Toolchain = {
             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);
+        let result = spawnSync(inv.command, inv.args, inv.options);
+        // Self-heal the Zephyr 4.3.99 dep-cycle regression (see the nuke comment
+        // above): when the cached .ninja_deps carries the cycle, ninja aborts with
+        // `dependency cycle` before compiling anything. The cycle lives in the
+        // build dir, not the sources — one pristine retry clears it and the build
+        // proceeds. On fixed Zephyr (>=4.4) this never fires.
+        let pristineRetry = false;
+        if (result.status !== 0 && isDependencyCycleFailure(combinedSpawnOutput(result))) {
+            try {
+                rmSync(buildDir, { recursive: true, force: true });
+            }
+            catch { /* may not exist */ }
+            result = spawnSync(inv.command, inv.args, inv.options);
+            pristineRetry = true;
+        }
         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;
+        const output = stdout + stderr + (pristineRetry
+            ? '\n[cuttlefish] dependency cycle detected in the cached build dir — retried with a pristine build'
+            : '');
         // 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';

package/dist/toolchain/scaffold.js

@@ -24,26 +24,35 @@ export function writeIfChanged(filePath, content) {
     writeFileSync(filePath, content);
     return true;
 }
+/**
+ * Names of the cuttlefish-emitted C/C++ sources under src/ (top level only,
+ * matching the old `src/*.cpp src/*.c` glob; sorted so the generated
+ * CMakeLists.txt is stable across readdir orderings). Empty when no sources
+ * exist yet (first prepare call).
+ */
+function listEmittedSources(srcDir) {
+    if (!existsSync(srcDir))
+        return [];
+    const names = readdirSync(srcDir).filter((name) => name.endsWith('.cpp') || name.endsWith('.c'));
+    names.sort();
+    return names;
+}
 /**
  * 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
+ * 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
-            }
+    for (const name of listEmittedSources(srcDir)) {
+        try {
+            out += readFileSync(join(srcDir, name), 'utf8');
+        }
+        catch {
+            // ignore unreadable files
         }
     }
     return out;
@@ -118,8 +127,13 @@ export function scaffoldZephyrProject(projectRoot, debug = false, userKconfig, p
     };
     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.
+    // The canonical Zephyr CMake application. The emitted source list is
+    // explicit (no file(GLOB CONFIGURE_DEPENDS ...)): CONFIGURE_DEPENDS puts a
+    // cmake.verify_globs step in the ninja graph that spawns CMake to re-check
+    // the glob on every build, and the scaffold already rewrites this file via
+    // writeIfChanged whenever the emitted file set changes — which flips
+    // configChanged and reconfigures with the new list baked in.
+    const sourceFiles = listEmittedSources(srcDir);
     const cmakeLists = [
         '# Auto-generated by @typecad/framework-zephyr from cuttlefish.config.ts.',
         'cmake_minimum_required(VERSION 3.20.0)',
@@ -128,10 +142,18 @@ export function scaffoldZephyrProject(projectRoot, debug = false, userKconfig, p
         '',
         'project(zephyr_app)',
         '',
-        '# Collect cuttlefish-emitted sources.',
-        'file(GLOB app_sources src/*.cpp src/*.c)',
-        '',
-        'target_sources(app PRIVATE ${app_sources})',
+        ...(sourceFiles.length > 0
+            ? [
+                '# Cuttlefish-emitted sources. This list is regenerated whenever the',
+                '# emitted file set changes (the scaffold rewrites CMakeLists.txt).',
+                'target_sources(app PRIVATE',
+                ...sourceFiles.map((name) => `  src/${name}`),
+                ')',
+            ]
+            : [
+                '# No emitted sources yet — the scaffold regenerates this list on the',
+                '# next compile once src/ contains .cpp/.c files.',
+            ]),
         // 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)', ''] : ['']),

package/dist/toolchain/west-discover.js

@@ -67,9 +67,12 @@ export function isZephyrBase(dir) {
 }
 // ── Strategy 1: `west` on PATH ──────────────────────────────────────────────
 export function discoverFromPath() {
+    // shell only on Windows (where.exe resolution through cmd) — an args array
+    // with shell: true triggers Node's DEP0190 deprecation warning on Linux/
+    // macOS, where `which` is a plain executable that needs no shell.
     const which = spawnSync(IS_WIN ? 'where' : 'which', ['west'], {
         encoding: 'utf8',
-        shell: true,
+        shell: IS_WIN,
         windowsHide: true,
     });
     if (which.status !== 0)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@typecad/framework-zephyr",
-  "version": "1.0.0-alpha.11",
+  "version": "1.0.0-alpha.13",
   "description": "TypeCAD framework package for the Zephyr RTOS — west/CMake build, devicetree-driven GPIO",
   "type": "module",
   "main": "./dist/index.js",
@@ -38,11 +38,11 @@
     "test:hw:mqtt": "cd ../../tests/hardware && npm exec -- cuttlefish-test mqtt-client.test.ts"
   },
   "dependencies": {
-    "@typecad/cuttlefish": "1.0.0-alpha.11"
+    "@typecad/cuttlefish": "1.0.0-alpha.13"
   },
   "devDependencies": {
-    "@typecad/expect": "1.0.0-alpha.11",
-    "@typecad/board-xiao-nrf52840": "1.0.0-alpha.11",
+    "@typecad/expect": "1.0.0-alpha.13",
+    "@typecad/board-xiao-nrf52840": "1.0.0-alpha.13",
     "typescript": "^5.7.3"
   },
   "license": "MIT",

package/src/display/index.ts

@@ -18,7 +18,7 @@ import { DEFAULT_ZEPHYR_DISPLAY_PROFILE, type ZephyrDisplayProfile } from './pro
 // and consumers can reach them from the package barrel.
 export { zephyrUiDisplayAdapter, zephyrDisplayAdapterGenerator } from './ui-adapter.js';
 export { zephyrTouchAdapter } from './touch-adapter.js';
-export { ZEPHYR_DISPLAY_PROFILES, DEFAULT_ZEPHYR_DISPLAY_PROFILE } from './profiles.js';
+export { ZEPHYR_DISPLAY_PROFILES, DEFAULT_ZEPHYR_DISPLAY_PROFILE, BUILT_IN_PROFILES } from './profiles.js';
 export type { ZephyrDisplayProfile } from './profiles.js';
 
 export interface DisplayState {