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

package/src/toolchain/debug-config.ts

@@ -17,6 +17,7 @@
 
 import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync } from 'node:fs';
 import { join, resolve, dirname, relative } from 'node:path';
+import { ZephyrStrategy } from '../strategy.js';
 
 export interface DebugConfigOptions {
   /** Absolute path to the Zephyr project root (contains CMakeLists.txt + src/). */
@@ -34,8 +35,10 @@ export interface DebugConfigOptions {
 }
 
 /**
- * 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).
  *
@@ -43,24 +46,94 @@ export interface DebugConfigOptions {
  * omits gdbPath and relies on Cortex-Debug's default resolution).
  */
 export function resolveGdbPath(buildDir: string, target: string): string | undefined {
+  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();
-  } catch {
-    return undefined;
+  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
+    }
   }
-  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).
+  // No build dir yet (project just created): probe known SDK locations.
+  for (const sdkRoot of discoverZephyrSdkRoots()) {
+    const p = gdbPathFromSdkRoot(sdkRoot);
+    if (p) return p;
+  }
+  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: string): string | undefined {
   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: string, b: string): number {
+  const segsOf = (v: string): number[] => 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?: {
+  home?: string;
+  env?: Record<string, string | undefined>;
+}): string[] {
+  const env = opts?.env ?? process.env;
+  const home = opts?.home ?? (env.USERPROFILE || env.HOME || '');
+  const scanned: string[] = [];
+
+  const versionedDirs = (base: string): string[] => {
+    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
@@ -397,3 +470,53 @@ export function writeDebugConfig(o: DebugConfigOptions): void {
   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: {
+  /** 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[] {
+  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/src/toolchain/index.ts

@@ -20,7 +20,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 type { ToolchainOptions, CompileResult, UploadResult } from '@typecad/cuttlefish/api/shared';
 import { parseCompileErrors } from '@typecad/cuttlefish/api/shared';
 import { scaffoldZephyrProject, writeIfChanged } from './scaffold.js';
@@ -28,7 +28,7 @@ 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, type DisplayWiring, type TouchWiring } from '../dt-config/overlay.js';
+import { generateOverlay, type DisplayWiring, type TouchWiring, type OverlayDiagnostic } from '../dt-config/overlay.js';
 import { chipForTarget } from '../chips/index.js';
 import { detectZephyrVersion, checkZephyrCompat, resolveBoardTarget } from './compat.js';
 import { DEFAULT_ZEPHYR_DISPLAY_PROFILE } from '../display/profiles.js';
@@ -167,6 +167,33 @@ export function cleanseUploadOutput(
 }
 
 
+/**
+ * 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: string): boolean {
+  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: { stdout?: string | Buffer | null; stderr?: string | Buffer | null },
+): string {
+  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
@@ -306,6 +333,7 @@ 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 from the config display.touch section so the
@@ -344,6 +372,7 @@ export const Toolchain = {
       if (usesXpt) {
         touchWiring = { controller: 'xpt2046', ...(touchWiring ?? {}) };
       }
+      const overlayDiagnostics: OverlayDiagnostic[] = [];
       const overlay = generateOverlay(chip, {
         usesI2c: uses('i2c_'),
         usesSpi: uses('spi_'),
@@ -352,7 +381,10 @@ export const Toolchain = {
         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
@@ -367,16 +399,23 @@ export const Toolchain = {
     // 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 }); } catch { /* may not exist */ }
     }
 
@@ -404,11 +443,24 @@ export const Toolchain = {
       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/src/toolchain/scaffold.ts

@@ -25,24 +25,34 @@ export function writeIfChanged(filePath: string, content: string): boolean {
   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: string): string[] {
+  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: string): string {
-  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;
@@ -120,8 +130,13 @@ export function scaffoldZephyrProject(projectRoot: string, debug = false, userKc
   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)',
@@ -130,12 +145,18 @@ export function scaffoldZephyrProject(projectRoot: string, debug = false, userKc
     '',
     'project(zephyr_app)',
     '',
-    '# Collect cuttlefish-emitted sources. CONFIGURE_DEPENDS makes CMake re-',
-    '# check the glob when the source set changes (e.g. the transpiler removes',
-    '# a stale entry), instead of linking a file list from the last configure.',
-    'file(GLOB app_sources CONFIGURE_DEPENDS 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)', ''] : ['']),