@typecad/framework-zephyr 1.0.0-alpha.16 → 1.0.0-alpha.19

package/dist/toolchain/runners.d.ts

@@ -0,0 +1,16 @@
+export interface RunnersFacts {
+    /** The board's declared default debug runner (e.g. 'openocd', 'jlink'). */
+    readonly debugRunner?: string;
+    /** Absolute path to the arch gdb binary (config.gdb). */
+    readonly gdb?: string;
+    /** All runners the board configured. */
+    readonly runners: readonly string[];
+}
+/**
+ * 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 declare function parseRunnersYaml(text: string): RunnersFacts | undefined;
+/** Read the resolved runner facts for a build dir. undefined when absent/unparseable. */
+export declare function readRunnersFacts(buildDir: string): RunnersFacts | undefined;

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.
@@ -21,4 +21,7 @@ export declare function appendLibraryOverlayFragments(overlay: string, projectRo
  *
  * Idempotent. Mirrors scaffoldEspIdfProject's writeIfChanged discipline.
  */
-export declare function scaffoldZephyrProject(projectRoot: string, debug?: boolean, userKconfig?: Record<string, string>, psram?: 'opi' | 'quad'): boolean;
+export declare function scaffoldZephyrProject(projectRoot: string, debug?: boolean, userKconfig?: Record<string, string>, psram?: 'opi' | 'quad', trace?: {
+    enabled?: boolean;
+    intervalMs?: number;
+}): boolean;

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).
@@ -9,7 +9,9 @@
 import { writeFileSync, existsSync, mkdirSync, readFileSync, readdirSync } from 'node:fs';
 import { join } from 'node:path';
 import { resolveKconfigFragments } from '../dt-config/kconfig.js';
-import { scanSensorParts } from './index.js';
+import { scanSensorParts, scanStrips, scanHid, scanMatrix } from './index.js';
+import { profileFromEmittedSource, transportFor, panelControllerFor } from '../display/profiles.js';
+import { readDisplayBinding } from '../display/bindings.js';
 import { readCuttlefishLibrarySidecar } from '@typecad/cuttlefish/library-packages';
 import { SENSOR_PART_INFO } from '@typecad/hal';
 /** Write a file only if the content differs from the existing file.
@@ -28,7 +30,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 +63,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.
@@ -96,7 +98,7 @@ export function appendLibraryOverlayFragments(overlay, projectRoot) {
  *
  * Idempotent. Mirrors scaffoldEspIdfProject's writeIfChanged discipline.
  */
-export function scaffoldZephyrProject(projectRoot, debug = false, userKconfig, psram) {
+export function scaffoldZephyrProject(projectRoot, debug = false, userKconfig, psram, trace) {
     const srcDir = join(projectRoot, 'src');
     if (!existsSync(srcDir))
         mkdirSync(srcDir, { recursive: true });
@@ -122,6 +124,22 @@ export function scaffoldZephyrProject(projectRoot, debug = false, userKconfig, p
     const usage = {
         usesAdc: uses('adc_'),
         usesPwm: uses('pwm_'),
+        usesStrip: uses('led_strip'),
+        strips: scanStrips(src),
+        // Sensor parts drive CONFIG_W1 (1-Wire masters) and the exception
+        // lines; the same scan the exception block below re-runs.
+        sensorParts: scanSensorParts(src),
+        usesHid: uses('__tc_hid_'),
+        hidProtocol: scanHid(src),
+        usesMatrix: uses('__tc_matrix'),
+        matrix: scanMatrix(src),
+        usesPower: uses('sys_poweroff'),
+        usesClock: uses('__tc_rtc'),
+        usesCan: uses('can_'),
+        canLoopback: uses('CAN_MODE_LOOPBACK'),
+        usesI2s: uses('i2s_'),
+        // No chip facts at scaffold time — the prepare overlay omits the shim;
+        // the chip-aware build path synthesizes it.
         usesDac: uses('dac_') || uses('__tc_dac'),
         usesFS: uses('__tc_fs'),
         usesHwtimer: uses('counter_') || uses('__tc_hw'),
@@ -130,6 +148,9 @@ export function scaffoldZephyrProject(projectRoot, debug = false, userKconfig, p
         // call yet), but the shim still declared DEVICE_DT_GET(DT_NODELABEL(...))
         // so the overlay must enable the node or the device symbol is missing.
         usesI2c: uses('i2c_') || uses('__tc_i2c'),
+        // I2C target mode: every i2c.resp_* lowering calls i2c_target_register
+        // (and the shim's state carries the i2c_target_* vocabulary).
+        usesI2cTarget: uses('i2c_target_'),
         // DT-bound sensor parts: the __tc_sensor_* state references and the
         // sensor_sample_fetch/sensor_channel_get calls both carry the token.
         usesSensor: uses('sensor_') || uses('__tc_sensor'),
@@ -138,12 +159,32 @@ export function scaffoldZephyrProject(projectRoot, debug = false, userKconfig, p
         usesUart: uses('uart_') || uses('__tc_uart'),
         // USB CDC serial: every usb.* lowering calls into the __tc_usb<N>_* shim
         // (device + init helper emitted under usesUsb).
-        usesUsb: uses('__tc_usb'),
+        usesUsb: uses('__tc_usb0'),
         // STM32F4 DBGMCU keep-SWD-alive init present (emitted for stm32f4 socs).
         usesStm32DebugSleep: uses('__tc_stm32_dbgmcu'),
         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'),
+        // Display transport + controller: recovered from the profile marker the
+        // display adapters stamp into the emitted source (the profile registry is
+        // the single source of truth — no geometry re-derivation here).
+        ...(() => {
+            const profile = profileFromEmittedSource(src);
+            if (!profile)
+                return {};
+            // Registry profiles name a DT compatible via dtCompatible (the driver
+            // id itself isn't one); drop-in profiles use the driver string directly.
+            const bus = readDisplayBinding(profile.dtCompatible ?? profile.driver)?.busFamily;
+            if (bus === 'i2c')
+                return { displayBus: 'i2c' };
+            // Board-provided panels (native_sim's sdl_dc) carry their own fragments
+            // and no bus at all.
+            if (profile.boardProvidesDisplay)
+                return { displayKconfigExtra: profile.kconfig };
+            if (transportFor(profile) !== 'zephyr-display')
+                return {};
+            return { displayTransport: 'zephyr-display', displayController: panelControllerFor(profile) };
+        })(),
         usesTouch: uses('ft6336u') || uses('touch_'),
         // (The power HAL is removed; its former pm_/k_sleep token scan is gone —
         // nothing here must match tx_power_dbm's `power` substring.)
@@ -174,7 +215,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 +230,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 +258,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 +282,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 +297,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];
@@ -266,6 +307,29 @@ export function scaffoldZephyrProject(projectRoot, debug = false, userKconfig, p
             }
         }
     }
+    // ── Trace heartbeat Kconfig ────────────────────────────────────────────────
+    // zephyr.trace.enabled in typecad-hal.config.ts turns on the [TR: sampler
+    // (emitted by the strategy at transpile time from the same config record).
+    // The symbol set is exactly what the sampler calls: runtime stats
+    // (k_thread_runtime_stats_*), the monitor list (k_thread_foreach —
+    // kernel/thread_monitor.c only links under THREAD_MONITOR), thread names
+    // (k_thread_name_get/set), and stack inspection (0xAA fill +
+    // stack_info.size). User zephyr.kconfig overrides still win.
+    if (trace?.enabled === true) {
+        const traceSymbols = [
+            ['CONFIG_THREAD_RUNTIME_STATS', 'y'],
+            ['CONFIG_THREAD_MONITOR', 'y'],
+            ['CONFIG_THREAD_NAME', 'y'],
+            ['CONFIG_INIT_STACKS', 'y'],
+            ['CONFIG_THREAD_STACK_INFO', 'y'],
+        ];
+        prjConf.push('', '# Trace heartbeat (typecad-hal.config.ts → zephyr.trace).');
+        for (const [sym, val] of traceSymbols) {
+            if (userKconfig && userKconfig.hasOwnProperty(sym))
+                continue;
+            prjConf.push(`${sym}=${val}`);
+        }
+    }
     // Per-part Kconfig exceptions: catalog parts whose driver is NOT default-y
     // on its DT node carry extra lines here (empty today — every in-tree sensor
     // driver lights up from the node; the path exists so the first exception
@@ -279,10 +343,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)

package/dist/west-inventory.d.ts

@@ -0,0 +1,25 @@
+import type { ReadDir, ReadFile } from '@typecad/cuttlefish/api/shared';
+/** Normalize a path for case-insensitive, separator-agnostic comparison. */
+export declare function norm(p: string): string;
+/**
+ * Filter the west manifest to the modules whose sources were compiled in the
+ * last build. A module is "linked" iff some compiled translation unit lives
+ * under its abspath. If the build data is unparseable, no filtering is applied
+ * (degrade to listing all modules rather than reporting nothing).
+ */
+export declare function filterLinkedModules(ccText: string, modules: {
+    name: string;
+    abspath: string;
+}[]): {
+    name: string;
+    abspath: string;
+}[];
+/**
+ * Find the build's compile_commands.json path under `cwd`. Cuttlefish's Zephyr
+ * project root is the transpile output dir (e.g. `<cwd>/src/out`), so the
+ * build dir is `<root>/build` — not necessarily `<cwd>/build`. Check the
+ * common layouts, then fall back to a bounded search (skipping
+ * node_modules/.git/dist and dot-directories). Returns the PATH (the caller
+ * decides whether to read it); undefined when no build exists.
+ */
+export declare function findCompileCommandsPath(readFile: ReadFile, readdir: ReadDir, cwd?: string): string | undefined;

package/dist/west-inventory.js

@@ -0,0 +1,97 @@
+// ---------------------------------------------------------------------------
+// @typecad/framework-zephyr — shared west workspace ground truth
+//
+// The as-built inventory both `typecad-hal licenses` and `typecad-hal sbom`
+// report from: which west manifest modules the last build ACTUALLY compiled
+// (linked-module filtering via the build's compile_commands.json), plus the
+// build-directory discovery that locates it. A west manifest carries every
+// vendor HAL/library; almost none are linked by a single project — both the
+// license table and the SBOM scope to the linked set by default, so they stay
+// honest about what is actually inside the firmware.
+//
+// Moved out of licenses.ts when the sbom command grew a second consumer; the
+// behavior (case-insensitive, separator-agnostic path matching; degrade to
+// "no filtering" on unparseable build data) is unchanged.
+// ---------------------------------------------------------------------------
+import * as path from 'node:path';
+/** Normalize a path for case-insensitive, separator-agnostic comparison. */
+export function norm(p) {
+    return p.split('\\').join('/').toLowerCase();
+}
+/**
+ * Filter the west manifest to the modules whose sources were compiled in the
+ * last build. A module is "linked" iff some compiled translation unit lives
+ * under its abspath. If the build data is unparseable, no filtering is applied
+ * (degrade to listing all modules rather than reporting nothing).
+ */
+export function filterLinkedModules(ccText, modules) {
+    let arr;
+    try {
+        arr = JSON.parse(ccText);
+    }
+    catch {
+        return modules;
+    }
+    if (!Array.isArray(arr))
+        return modules;
+    // One normalized blob of every compiled source path; membership is then a
+    // substring check per module (O(modules) after an O(TUs) join).
+    const blob = arr
+        .map((e) => norm(typeof e?.file === 'string' ? e.file : ''))
+        .join('\n');
+    return modules.filter((m) => blob.includes(norm(m.abspath) + '/'));
+}
+/**
+ * Find the build's compile_commands.json path under `cwd`. Cuttlefish's Zephyr
+ * project root is the transpile output dir (e.g. `<cwd>/src/out`), so the
+ * build dir is `<root>/build` — not necessarily `<cwd>/build`. Check the
+ * common layouts, then fall back to a bounded search (skipping
+ * node_modules/.git/dist and dot-directories). Returns the PATH (the caller
+ * decides whether to read it); undefined when no build exists.
+ */
+export function findCompileCommandsPath(readFile, readdir, cwd = process.cwd()) {
+    const direct = [
+        path.join(cwd, 'build', 'compile_commands.json'),
+        path.join(cwd, 'out', 'build', 'compile_commands.json'),
+        path.join(cwd, 'src', 'out', 'build', 'compile_commands.json'),
+    ];
+    for (const c of direct) {
+        if (readFile(c))
+            return c;
+    }
+    // Bounded recursive search for a build/compile_commands.json.
+    const isCc = (p) => {
+        const n = norm(p);
+        return n.endsWith('/build/compile_commands.json') || n.endsWith('\\build\\compile_commands.json');
+    };
+    let found;
+    const seen = new Set();
+    const walk = (dir, depth) => {
+        if (found || depth > 4 || seen.has(dir))
+            return;
+        seen.add(dir);
+        let entries;
+        try {
+            entries = readdir(dir);
+        }
+        catch {
+            return;
+        }
+        for (const e of entries) {
+            const full = path.join(dir, e);
+            if (e === 'compile_commands.json' && isCc(full)) {
+                found = full;
+                return;
+            }
+        }
+        for (const e of entries) {
+            if (found)
+                return;
+            if (e === 'node_modules' || e === '.git' || e === 'dist' || e.startsWith('.'))
+                continue;
+            walk(path.join(dir, e), depth + 1);
+        }
+    };
+    walk(cwd, 0);
+    return found;
+}