@typecad/framework-zephyr 1.0.0-alpha.15 → 1.0.0-alpha.18

package/dist/toolchain/runners.js

@@ -0,0 +1,75 @@
+// ---------------------------------------------------------------------------
+// runners.ts — read west's resolved runner facts from a built Zephyr tree.
+//
+// After any successful `west build`, Zephyr writes build/zephyr/runners.yaml —
+// the FULLY RESOLVED debug/flash configuration for the board: the arch gdb
+// binary, the openocd binary + its script search dirs, the jlink device name,
+// the board's declared default debug runner. It is the single source of debug
+// truth west itself uses (`west debug` / `west debugserver` read the same
+// file), so cuttlefish reads it instead of reconstructing any of this.
+//
+// The parser below is deliberately minimal: it understands exactly the shape
+// west's run_common.py emits — top-level scalars, a list section whose items
+// sit at column 0, and a nested config map — and ignores everything else
+// (e.g. the args section). A general YAML dependency is not worth it for one
+// machine-generated file.
+// ---------------------------------------------------------------------------
+import fs from 'node:fs';
+import { join } from 'node:path';
+/**
+ * Parse the subset of runners.yaml cuttlefish consumes. Exported for tests.
+ * Returns undefined on shapes it does not understand (callers treat as
+ * "no facts" — never crash a build over diagnostics data).
+ */
+export function parseRunnersYaml(text) {
+    const runners = [];
+    let debugRunner;
+    let gdb;
+    // Section state: '' = top level, 'runners' = the list, 'config' = the map.
+    let section = '';
+    for (const rawLine of text.split(/\r?\n/)) {
+        const trimmed = rawLine.trim();
+        if (trimmed.startsWith('#') || trimmed === '')
+            continue;
+        // List items — west writes the runners list at column 0 and
+        // openocd_search indented; both belong to the last-opened section.
+        if (trimmed.startsWith('- ')) {
+            const item = trimmed.slice(2).trim();
+            if (section === 'runners')
+                runners.push(item);
+            continue; // other sections' lists (openocd_search, args) are unused
+        }
+        const indent = rawLine.length - rawLine.trimStart().length;
+        const m = trimmed.match(/^([A-Za-z0-9_.-]+):\s*(.*)$/);
+        if (!m)
+            continue; // e.g. west's empty-list `[]` lines — skip, don't bail
+        const [, key, value] = m;
+        if (indent === 0) {
+            if (key === 'runners') {
+                section = 'runners';
+                continue;
+            }
+            if (key === 'config') {
+                section = 'config';
+                continue;
+            }
+            section = '';
+            if (key === 'debug-runner' && value)
+                debugRunner = value.trim();
+            continue;
+        }
+        if (section === 'config' && key === 'gdb' && value) {
+            gdb = value.trim().replace(/^['"]|['"]$/g, '');
+        }
+    }
+    return { runners, ...(debugRunner ? { debugRunner } : {}), ...(gdb ? { gdb } : {}) };
+}
+/** Read the resolved runner facts for a build dir. undefined when absent/unparseable. */
+export function readRunnersFacts(buildDir) {
+    try {
+        return parseRunnersYaml(fs.readFileSync(join(buildDir, 'zephyr', 'runners.yaml'), 'utf-8'));
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/toolchain/scaffold.d.ts

@@ -2,7 +2,7 @@
  *  Returns true when the file was written (content changed or file was new). */
 export declare function writeIfChanged(filePath: string, content: string): boolean;
 /**
- * Append cuttlefish library packages' devicetree overlay fragments to the
+ * Append typecad-hal library packages' devicetree overlay fragments to the
  * generated overlay. Library entries come from the transpiler's libraries.json
  * sidecar (next to the emitted sources) and are already gated on the
  * library's include token appearing in the emitted sources — no re-detection.

package/dist/toolchain/scaffold.js

@@ -1,7 +1,7 @@
 // ---------------------------------------------------------------------------
 // Zephyr project scaffolding
 //
-// Writes the CMakeLists.txt + prj.conf around the cuttlefish-emitted src/main.cpp
+// Writes the CMakeLists.txt + prj.conf around the typecad-hal-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).
@@ -28,7 +28,7 @@ export function writeIfChanged(filePath, content) {
     return true;
 }
 /**
- * Names of the cuttlefish-emitted C/C++ sources under src/ (top level only,
+ * Names of the typecad-hal-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).
@@ -61,7 +61,7 @@ function readEmittedSources(srcDir) {
     return out;
 }
 /**
- * Append cuttlefish library packages' devicetree overlay fragments to the
+ * Append typecad-hal library packages' devicetree overlay fragments to the
  * generated overlay. Library entries come from the transpiler's libraries.json
  * sidecar (next to the emitted sources) and are already gated on the
  * library's include token appearing in the emitted sources — no re-detection.
@@ -174,7 +174,7 @@ export function scaffoldZephyrProject(projectRoot, debug = false, userKconfig, p
     // 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.',
+        '# Auto-generated by @typecad/framework-zephyr from typecad-hal.config.ts.',
         'cmake_minimum_required(VERSION 3.20.0)',
         '',
         '# The app is its own board root: MCU-only targets generate an out-of-tree',
@@ -189,7 +189,7 @@ export function scaffoldZephyrProject(projectRoot, debug = false, userKconfig, p
         '',
         ...(sourceFiles.length > 0
             ? [
-                '# Cuttlefish-emitted sources. This list is regenerated whenever the',
+                '# TypeCAD-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}`),
@@ -217,12 +217,12 @@ export function scaffoldZephyrProject(projectRoot, debug = false, userKconfig, p
     // 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.',
+        '# Auto-generated by @typecad/framework-zephyr from typecad-hal.config.ts.',
+        '# Edit in typecad-hal.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',
+        '# Route printf/stdout to the console UART (needed by the typecad-hal',
         '# test runner protocol, which uses printf via __tc_print/__tc_println).',
         'CONFIG_STDOUT_CONSOLE=y',
         'CONFIG_PRINTK=y',
@@ -241,7 +241,7 @@ export function scaffoldZephyrProject(projectRoot, debug = false, userKconfig, p
             wifiHeaderEmitted = true;
         }
         // Skip auto-detected symbols that the user explicitly overrides
-        // in cuttlefish.config.ts zephyr.kconfig — the user value is
+        // in typecad-hal.config.ts zephyr.kconfig — the user value is
         // emitted in the User Kconfig section below and takes precedence.
         if (userKconfig && userKconfig.hasOwnProperty(sym))
             continue;
@@ -256,7 +256,7 @@ export function scaffoldZephyrProject(projectRoot, debug = false, userKconfig, p
     // zephyr.kconfig overrides still win.
     const libraryEntries = readCuttlefishLibrarySidecar(srcDir);
     if (libraryEntries.length > 0) {
-        prjConf.push('', '# Library packages (cuttlefish.library.json contributions).');
+        prjConf.push('', '# Library packages (typecad-hal.library.json contributions).');
         for (const entry of libraryEntries) {
             for (const line of entry.kconfig) {
                 const sym = line.split('=')[0];
@@ -279,10 +279,10 @@ export function scaffoldZephyrProject(projectRoot, debug = false, userKconfig, p
                 prjConf.push(line);
         }
     }
-    // Emit user-specified Kconfig from cuttlefish.config.ts zephyr.kconfig.
+    // Emit user-specified Kconfig from typecad-hal.config.ts zephyr.kconfig.
     // These override any matching auto-detected symbol (skipped above).
     if (userKconfig) {
-        prjConf.push('', '# User Kconfig (cuttlefish.config.ts → zephyr.kconfig).');
+        prjConf.push('', '# User Kconfig (typecad-hal.config.ts → zephyr.kconfig).');
         for (const [sym, val] of Object.entries(userKconfig)) {
             prjConf.push(`${sym}=${val}`);
         }

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

@@ -30,6 +30,12 @@ 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;
+/** The installer-written SDK dir for the default micromamba env, when the
+ *  installer has run on this machine. Read WITHOUT requiring micromamba
+ *  mode — a PATH/venv west install is enriched with it so builds spawned
+ *  through it still pin the installer's SDK (otherwise Zephyr's CMake
+ *  searches $HOME and can pick up a stray, older SDK). */
+export declare function installerSdkDir(): string | undefined;
 /** The installer-written ZEPHYR_BASE of the micromamba env, fs-only (no
  *  spawn) — the cheap probe shared by board-catalog overlay discovery.
  *  Undefined when the installer env or its env-vars file is absent. */

package/dist/toolchain/west-discover.js

@@ -11,7 +11,7 @@
 //   1. `west` already on PATH (env already activated / global install).
 //   2. $ZEPHYR_BASE venv: ${ZEPHYR_BASE}/../.venv/<python> -m west.
 //   3. micromamba env from @typecad/zephyr-installer (invoked via `micromamba run`,
-//      so cuttlefish builds work with NO manual activation).
+//      so typecad-hal builds work with NO manual activation).
 //   4. Well-known workspace layouts: ~/zephyrproject/.venv, /opt/zephyrproject/.
 //      venv, etc.
 //   5. System pythons (`python`, `python3`, `py`) via `-m west`.
@@ -111,6 +111,34 @@ export function discoverFromZephyrBase() {
         source: 'zephyr-base-venv',
     };
 }
+/** The installer-written SDK dir for the default micromamba env, when the
+ *  installer has run on this machine. Read WITHOUT requiring micromamba
+ *  mode — a PATH/venv west install is enriched with it so builds spawned
+ *  through it still pin the installer's SDK (otherwise Zephyr's CMake
+ *  searches $HOME and can pick up a stray, older SDK). */
+export function installerSdkDir() {
+    const mm = findMicromamba();
+    if (!mm)
+        return undefined;
+    const envName = process.env.TYPECAD_ZEPHYR_ENV || 'zephyr';
+    const envDir = join(mm.rootPrefix, 'envs', envName);
+    if (!existsSync(envDir))
+        return undefined;
+    const sdk = readMicromambaEnvVar(envDir, 'TYPECAD_ZEPHYR_SDK_INSTALL_DIR');
+    return sdk && existsSync(sdk) ? sdk : undefined;
+}
+/**
+ * The micromamba env created by `@typecad/zephyr-installer`. The env's west
+ * lives at envs/<name>/bin/west (POSIX) or Scripts/west.exe (Windows). Found
+ * installs are invoked via `micromamba run -n <name> west …` (see
+ * west-spawn.ts), which sets up the env's full PATH (cmake/ninja/dtc) AND runs
+ * the activation hook (ZEPHYR_BASE / ZEPHYR_SDK_INSTALL_DIR) — so builds work
+ * with NO manual `micromamba activate`. This is what makes a fresh
+ * `typecad-hal build` succeed in any project without the user activating.
+ *
+ * Env name defaults to "zephyr"; override via TYPECAD_ZEPHYR_ENV. File-check
+ * based (no spawn) so it's cheap to run on every invocation.
+ */
 // ── Strategy 3: micromamba env (the @typecad/zephyr-installer install) ─────
 // Locate the micromamba binary + root prefix. The installer downloads
 // micromamba to $MAMBA_ROOT_PREFIX/bin (POSIX) or Library/bin (Windows); the
@@ -123,18 +151,6 @@ function findMicromamba() {
         : join(root, 'bin', 'micromamba');
     return existsSync(exe) ? { exe, rootPrefix: root } : null;
 }
-/**
- * The micromamba env created by `@typecad/zephyr-installer`. The env's west
- * lives at envs/<name>/bin/west (POSIX) or Scripts/west.exe (Windows). Found
- * installs are invoked via `micromamba run -n <name> west …` (see
- * west-spawn.ts), which sets up the env's full PATH (cmake/ninja/dtc) AND runs
- * the activation hook (ZEPHYR_BASE / ZEPHYR_SDK_INSTALL_DIR) — so cuttlefish
- * builds work with NO manual `micromamba activate`. This is what makes a fresh
- * `cuttlefish build` succeed in any project without the user activating.
- *
- * Env name defaults to "zephyr"; override via TYPECAD_ZEPHYR_ENV. File-check
- * based (no spawn) so it's cheap to run on every cuttlefish invocation.
- */
 /** Read a TYPECAD_ZEPHYR_* value from the installer-written env-vars file in
  *  a micromamba env. Handles .sh (export VAR="val"), .bat (set "VAR=val"),
  *  and .ps1 ($env:VAR = "val"). Returns undefined if absent/unreadable. */
@@ -284,6 +300,13 @@ export function discoverWest() {
             install = null;
         }
         if (install) {
+            // A PATH/venv west install knows nothing about the installer's SDK.
+            // Enrich it: west-spawn pins the child's ZEPHYR_SDK_INSTALL_DIR to the
+            // installer dir, so Zephyr's CMake cannot pick up a stray SDK from
+            // $HOME (a version mismatch that only surfaces at configure time).
+            if (!install.sdkInstallDir) {
+                install.sdkInstallDir = installerSdkDir();
+            }
             cachedDiscover = install;
             return install;
         }

package/dist/toolchain/west-spawn.js

@@ -49,6 +49,12 @@ export function buildEnv(install) {
     // flashing works without activation. $ZEPHYR_SDK_INSTALL_DIR (set by an
     // activated env) wins over the discovered install dir.
     const sdkRoot = env.ZEPHYR_SDK_INSTALL_DIR || install.sdkInstallDir;
+    // Pin the west/cmake child to the discovered SDK: without this, Zephyr's
+    // FindZephyr-sdk searches $HOME and can latch onto a stray, older SDK —
+    // a configure-time version failure that only surfaces in the build log.
+    if (!env.ZEPHYR_SDK_INSTALL_DIR && install.sdkInstallDir) {
+        env.ZEPHYR_SDK_INSTALL_DIR = install.sdkInstallDir;
+    }
     const openocdBin = sdkRoot ? join(sdkRoot, 'hosttools', 'openocd', 'bin') : undefined;
     const prepend = [
         openocdBin !== undefined && existsSync(openocdBin) ? openocdBin : undefined,
@@ -92,7 +98,7 @@ export function westSpawn(westArgs, baseOptions) {
         throw new Error([
             'west (the Zephyr build tool) was not found.',
             '',
-            'cuttlefish looked for it on PATH, in $ZEPHYR_BASE/.venv, in common',
+            'typecad-hal 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:",
             '',
@@ -113,7 +119,7 @@ export function westSpawn(westArgs, baseOptions) {
     if (install.mode === 'micromamba' && install.micromambaExe) {
         // `micromamba run -n <env> west …` sets up the env's full PATH
         // (cmake/ninja/dtc) and runs the activation hook (ZEPHYR_BASE /
-        // ZEPHYR_SDK_INSTALL_DIR), so cuttlefish builds work WITHOUT the user
+        // ZEPHYR_SDK_INSTALL_DIR), so typecad-hal builds work WITHOUT the user
         // activating the env. Inject MAMBA_ROOT_PREFIX so micromamba finds envs.
         const mmEnv = { ...env };
         if (install.mambaRootPrefix)