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

package/dist/toolchain/index.js

@@ -10,22 +10,25 @@
 // a SDK root is discovered. See west-discover.ts / west-spawn.ts.
 //
 // The board target is carried via frameworkData.buildTarget (populated as
-// ToolchainOptions.buildTarget by the cuttlefish CLI), defaulting to the
+// ToolchainOptions.buildTarget by the typecad-hal CLI), defaulting to the
 // framework's canonical MVP target (xiao_ble).
 //
 // Mirrors framework-esp32/src/toolchain/index.ts structure: projectRoot derived
 // from outputDir, prepare is a no-op (scaffold happens in compile when the
 // target is known), GCC errors parsed via the shared parseCompileErrors helper.
 // ---------------------------------------------------------------------------
-import { spawnSync } from 'node:child_process';
+import { spawn, spawnSync } from 'node:child_process';
+import { connect as netConnect } from 'node:net';
 import { basename, delimiter, dirname, join } from 'node:path';
 import { readdirSync, readFileSync, mkdirSync, rmSync, existsSync, writeFileSync } from 'node:fs';
 import { parseCompileErrors } from '@typecad/cuttlefish/api/shared';
 import { scaffoldZephyrProject, writeIfChanged, appendLibraryOverlayFragments } from './scaffold.js';
 import { parseZephyrDts, asBuiltJson } from '../as-built.js';
+import { stampBuildSbom } from '../sbom.js';
 import { westSpawn, buildEnv } from './west-spawn.js';
 import { discoverWest } from './west-discover.js';
-import { writeDebugConfig, resolveDebugLocations } from './debug-config.js';
+import { writeDebugConfig, resolveDebugLocations, debugArtifactsNeedRewrite, DEBUG_SERVER_PORT, DEBUG_SERVER_TCL_PORT } from './debug-config.js';
+import { readRunnersFacts } from './runners.js';
 import { bossacTouchReset } from './bossac-touch.js';
 import { ZephyrStrategy } from '../strategy.js';
 import { generateOverlay } from '../dt-config/overlay.js';
@@ -34,7 +37,7 @@ import { NO_BOARD_CHIP } from '../chips/index.js';
 import { resolveChipFromBoard } from '../chips/resolve.js';
 import { pwmDtAliasToken } from '../lowering/pwm.js';
 import { detectZephyrVersion, checkZephyrCompat, resolveBoardTarget } from './compat.js';
-import { DEFAULT_ZEPHYR_DISPLAY_PROFILE } from '../display/profiles.js';
+import { DEFAULT_ZEPHYR_DISPLAY_PROFILE, profileFromEmittedSource } from '../display/profiles.js';
 /**
  * Resolve the chip for a build the same way the strategy does at emit time —
  * from the board constants the transpile persisted next to the emitted
@@ -194,6 +197,36 @@ function scanPwmUsedPins(src, chip) {
     }
     return pins;
 }
+export function scanMatrix(src) {
+    // The on_key lowering's comment marker carries the construction lists.
+    const m = src.match(/cuttlefish-matrix: rows=([\d,]*) cols=([\d,]*)/);
+    if (!m)
+        return undefined;
+    const rows = m[1] ? m[1].split(',').filter(Boolean).map(Number) : [];
+    const cols = m[2] ? m[2].split(',').filter(Boolean).map(Number) : [];
+    if (rows.length === 0 || cols.length === 0)
+        return undefined;
+    return { rows, cols };
+}
+export function scanHid(src) {
+    // The shim's report buffer names are the presence signal.
+    if (src.includes('__tc_mouse_report'))
+        return 'mouse';
+    if (src.includes('__tc_kb_report'))
+        return 'keyboard';
+    return undefined;
+}
+export function scanStrips(src) {
+    // The shim's buffer declaration is the presence signal:
+    // `static struct led_rgb __tc_strip<N>_buf[<COUNT>];`
+    const out = new Map();
+    for (const m of src.matchAll(/__tc_strip(\d+)_buf\[(\d+)\]/g)) {
+        const idx = Number(m[1]);
+        const count = Number(m[2]);
+        out.set(idx, Math.max(out.get(idx) ?? 0, count));
+    }
+    return [...out.entries()].map(([index, count]) => ({ index, count }));
+}
 /**
  * Bus controller indexes the emitted sources actually reference — the shim
  * declares one `__tc_<bus><N>_dev` state block per used instance (gated by
@@ -228,13 +261,23 @@ export function scanSpiTargets(src) {
 }
 export function scanSensorParts(src) {
     const out = new Map();
+    // 1-Wire sensors: the stem carries the data pin (w1 master's GPIO).
+    for (const m of src.matchAll(/__tc_sensor_([a-z0-9_]+)_w1_p(\d+)_dev\b/g)) {
+        out.set(`${m[1]}|w1|${m[2]}`, { part: m[1], busIndex: 0, port: parseInt(m[2], 10), busKind: 'w1', spiHz: 0, spiMode: 0, alertPin: -1, resolution: 12 });
+    }
     for (const m of src.matchAll(/__tc_sensor_([a-z0-9_]+)_(i2c|spi)(\d+)_(0x[0-9a-f]+|cs[0-9]+)_dev\b/g)) {
         const port = m[4].startsWith('0x') ? parseInt(m[4], 16) : parseInt(m[4].slice(2), 10);
-        const ref = { part: m[1], busIndex: parseInt(m[3], 10), port, busKind: m[2], spiHz: 0, spiMode: 0, alertPin: -1 };
+        const ref = { part: m[1], busIndex: parseInt(m[3], 10), port, busKind: m[2], spiHz: 0, spiMode: 0, alertPin: -1, resolution: 12 };
         out.set(`${ref.part}|${ref.busKind}${ref.busIndex}|${ref.port}`, ref);
     }
     // Construction facts ride the state block's config comment — merge by
     // nodelabel so the scanner stays the single source for the overlay.
+    for (const m of src.matchAll(/tc-sensor-cfg: tc_([a-z0-9_]+)_w1_p(\d+) res=(\d+)/g)) {
+        const key = `${m[1]}|w1|${m[2]}`;
+        const existing = out.get(key);
+        if (existing)
+            existing.resolution = parseInt(m[3], 10);
+    }
     for (const m of src.matchAll(/tc-sensor-cfg: tc_([a-z0-9_]+)_(i2c|spi)(\d+)_(0x[0-9a-f]+|cs[0-9]+) hz=(\d+) mode=(\d+) alert=(-?\d+)/g)) {
         const port = m[4].startsWith('0x') ? parseInt(m[4], 16) : parseInt(m[4].slice(2), 10);
         const key = `${m[1]}|${m[2]}${m[3]}|${port}`;
@@ -255,12 +298,12 @@ function targetFromOptions(o) {
     const fcTarget = o.frameworkConfig?.target;
     const board = o.buildTarget ?? fcTarget;
     if (!board) {
-        throw new Error('No build target: set board: in cuttlefish.config.ts (or frameworkData.buildTarget for custom-board projects).');
+        throw new Error('No build target: set board: in typecad-hal.config.ts (or frameworkData.buildTarget for custom-board projects).');
     }
     return board;
 }
 /**
- * Derive the Zephyr project root from the cuttlefish-emitted source path.
+ * Derive the Zephyr project root from the typecad-hal-emitted source path.
  *
  * Cuttlefish emits `src/main.cpp` under the output dir. The CLI passes
  * `sourcePath` = full path to `main.cpp` and `outputDir` = its parent (`src/`).
@@ -280,6 +323,23 @@ export function projectRootFromOptions(o) {
  */
 const BUILD_TIMEOUT_MS = 600_000;
 const FLASH_TIMEOUT_MS = 120_000;
+/**
+ * The board a cached build dir was configured for (CMakeCache.txt's
+ * BOARD:STRING — the exact value passed to `west build -b`), or undefined
+ * when no cache exists. compile() compares it against the requested board
+ * and nukes the dir on mismatch: `west build`'s --pristine=auto covers
+ * cmake/config churn, NOT a board switch — west aborts with "refusing to
+ * proceed without --force", and cuttlefish doesn't forward that flag.
+ */
+export function cachedBuildBoard(buildDir) {
+    try {
+        return readFileSync(join(buildDir, 'CMakeCache.txt'), 'utf-8')
+            .match(/^BOARD:STRING=(.+)$/m)?.[1]?.trim() || undefined;
+    }
+    catch {
+        return undefined; // no build dir / unreadable cache — treat as fresh
+    }
+}
 export function resolveProbeMethod(zc, chip, purpose = 'flash') {
     const probe = zc?.probe;
     const runner = zc?.runner;
@@ -287,7 +347,7 @@ export function resolveProbeMethod(zc, chip, purpose = 'flash') {
     if (probe && runner) {
         return {
             ok: false,
-            error: `cuttlefish.config.ts sets both zephyr.probe ('${probe}') and zephyr.runner ('${runner}'). ` +
+            error: `typecad-hal.config.ts sets both zephyr.probe ('${probe}') and zephyr.runner ('${runner}'). ` +
                 `They are two ways to choose the probe method — remove one.`,
         };
     }
@@ -385,7 +445,7 @@ function openocdProbeSession(buildDir, zc, chip, commands) {
     let cfgArgs;
     let sessionCfg;
     if (cfgLines && cfgLines.length > 0) {
-        sessionCfg = join(buildDir, 'cuttlefish-probe.cfg');
+        sessionCfg = join(buildDir, 'typecad-hal-probe.cfg');
     }
     else {
         // The board target's qualifier ('blackpill_f411ce/stm32f411xe' →
@@ -612,11 +672,13 @@ export const Toolchain = {
         const usesDisplay = uses('display_write') || uses('display_init')
             || uses('display_fill_rect') || uses('__tc_display_dev')
             || uses('CuttlefishDisplayTarget');
-        // Both registered Zephyr display profiles use dtLabel 'display0', so the
-        // default profile's overlay block (&display0 { status="okay" }) is correct
-        // for either driver. Thread a non-default profile here only if a future
-        // board carries a display node under a different nodelabel.
-        const displayProfile = usesDisplay ? DEFAULT_ZEPHYR_DISPLAY_PROFILE : undefined;
+        // Recover the exact display profile from the marker the adapter stamped
+        // into the emitted source (the registry is the single source of truth).
+        // Fall back to the default profile only when a display is used but no
+        // marker matched (e.g. hand-written source).
+        const displayProfile = usesDisplay
+            ? (profileFromEmittedSource(src) ?? 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_');
@@ -635,12 +697,29 @@ export const Toolchain = {
             spiTargets: spiTargetParts,
             usesSpi: uses('spi_') || uses('__tc_spi') || spiTargetParts.length > 0,
             usesUart: uses('__tc_uart'),
-            usesUsb: uses('__tc_usb'),
+            usesUsb: uses('__tc_usb0'),
             usesPwm: uses('pwm_'),
             usesAdc: uses('adc_'),
             adcReadPins: scanAdcReadPins(src, chip),
             dacWritePins: scanDacWritePins(src),
             pwmUsedPins: scanPwmUsedPins(src, chip),
+            usesStrip: uses('led_strip'),
+            strips: scanStrips(src),
+            usesClock: uses('__tc_rtc'),
+            usesCan: uses('can_'),
+            canLoopback: uses('CAN_MODE_LOOPBACK'),
+            usesI2s: uses('i2s_'),
+            clockShimCounter: chip.hwtimer && chip.hwtimer.controllers.length > 0
+                ? {
+                    label: chip.hwtimer.controllers[0].nodeLabel,
+                    ...(chip.hwtimer.controllers[0].counterParent ? { parent: chip.hwtimer.controllers[0].counterParent } : {}),
+                }
+                : undefined,
+            usesHid: uses('__tc_hid_'),
+            hidProtocol: scanHid(src),
+            usesMatrix: uses('__tc_matrix'),
+            matrix: scanMatrix(src),
+            usesPower: uses('sys_poweroff'),
             i2cUsedInstances: scanUsedBusInstances(src, chip.i2c?.controllers, 'i2c'),
             spiUsedInstances: scanUsedBusInstances(src, chip.spi?.controllers, 'spi'),
             uartUsedInstances: scanUsedBusInstances(src, chip.uart?.controllers, 'uart'),
@@ -704,7 +783,8 @@ export const Toolchain = {
         const isGdbDebug = o.debug === true && debugMode === 'gdb';
         const zc = o.zephyrConfig;
         const userKconfig = zc?.kconfig;
-        const configChanged = scaffoldZephyrProject(projectRoot, isGdbDebug, userKconfig, o.psram);
+        const traceCfg = zc?.trace;
+        const configChanged = scaffoldZephyrProject(projectRoot, isGdbDebug, userKconfig, o.psram, traceCfg);
         // Regenerate the DT overlay for the ACTUAL target board. prepare() writes
         // it for the default board (the real target is unknown until compile), so
         // the <default>.overlay it wrote does not match `west build -b <board>`.
@@ -714,7 +794,7 @@ export const Toolchain = {
             // Custom-board generation: an MCU-only target (no board package) has no
             // upstream Zephyr board — generate one under boards/typecad/<name>/ from
             // the chip's silicon data. Opt-in via `zephyr.customBoard: true` in
-            // cuttlefish.config.ts; the board takes its name from the build target.
+            // typecad-hal.config.ts; the board takes its name from the build target.
             // Idempotent — regenerated on every compile, before the overlay pass.
             if (zc?.customBoard === true) {
                 const generated = generateCustomBoard(projectRoot, chip, board.split('/')[0]);
@@ -738,28 +818,22 @@ export const Toolchain = {
             const usesDisplay = uses('display_write') || uses('display_init')
                 || uses('display_fill_rect') || uses('__tc_display_dev')
                 || uses('CuttlefishDisplayTarget');
-            // Derive the display dimensions from the emitted adapter code
-            // (display_width/height return the profile's w/h). This ensures the DT
-            // overlay's width/height match the panel the adapter targets, not the
-            // default profile — critical for drivers like ST7796S that initialize
-            // the panel geometry from the DT node.
-            let displayProfile = usesDisplay ? DEFAULT_ZEPHYR_DISPLAY_PROFILE : undefined;
-            if (usesDisplay) {
-                const wMatch = src.match(/display_width\(\)\s*\{\s*return\s+(\d+)\s*;\s*\}/);
-                const hMatch = src.match(/display_height\(\)\s*\{\s*return\s+(\d+)\s*;\s*\}/);
-                if (wMatch && hMatch) {
-                    displayProfile = {
-                        ...DEFAULT_ZEPHYR_DISPLAY_PROFILE,
-                        width: parseInt(wMatch[1], 10),
-                        height: parseInt(hMatch[1], 10),
-                    };
-                }
-            }
+            // Recover the exact display profile from the marker the adapter emitted
+            // (`typecad-display-profile: <driver>`), so the DT overlay's compatible
+            // string, geometry, and rotation match the panel the adapter targets.
+            // The width/height regex this replaces could produce franken-profiles —
+            // e.g. an ST7796S build (480x320) on the default ILI9341 profile's
+            // controller/compatible, which emitted an ilitek,ili9341 DT node for a
+            // panel the ST7796S adapter drives.
+            const displayProfile = usesDisplay
+                ? (profileFromEmittedSource(src) ?? DEFAULT_ZEPHYR_DISPLAY_PROFILE)
+                : undefined;
             // Extract display pin wiring (cs/dc/rst/spiFrequency/spiPins) from the
             // config display section so the DT overlay wires the MIPI DBI bridge to
             // the correct GPIOs + SPI bus pins.
             const dispCfg = o.display;
             const spiPins = (dispCfg?.spiPins ?? undefined);
+            const i2cPins = (dispCfg?.i2cPins ?? undefined);
             const wiring = dispCfg
                 ? {
                     cs: typeof dispCfg.cs === 'number' ? dispCfg.cs : undefined,
@@ -769,8 +843,12 @@ export const Toolchain = {
                     sck: typeof spiPins?.sck === 'number' ? spiPins.sck : undefined,
                     mosi: typeof spiPins?.mosi === 'number' ? spiPins.mosi : undefined,
                     miso: typeof spiPins?.miso === 'number' ? spiPins.miso : undefined,
+                    sda: typeof i2cPins?.sda === 'number' ? i2cPins.sda : undefined,
+                    scl: typeof i2cPins?.scl === 'number' ? i2cPins.scl : undefined,
                     backlightPin: typeof dispCfg.backlightPin === 'number' ? dispCfg.backlightPin : undefined,
                     tearingEffectPin: typeof dispCfg.tearingEffectPin === 'number' ? dispCfg.tearingEffectPin : undefined,
+                    busyPin: typeof dispCfg.busyPin === 'number' ? dispCfg.busyPin : undefined,
+                    address: typeof dispCfg.address === 'number' ? dispCfg.address : undefined,
                 }
                 : undefined;
             // Extract touch pin wiring from the config display.touch section so the
@@ -822,13 +900,30 @@ export const Toolchain = {
                 spiTargets: spiTargetParts,
                 usesSpi: uses('spi_') || uses('__tc_spi') || spiTargetParts.length > 0,
                 usesUart: uses('__tc_uart'),
-                usesUsb: uses('__tc_usb'),
+                usesUsb: uses('__tc_usb0'),
                 usesPwm: uses('pwm_'),
                 usesAdc: uses('adc_'),
                 adcReadPins: scanAdcReadPins(src, chip),
                 usesDac: uses('dac_') || uses('__tc_dac'),
                 dacWritePins: scanDacWritePins(src),
                 pwmUsedPins: scanPwmUsedPins(src, chip),
+                usesStrip: uses('led_strip'),
+                strips: scanStrips(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_'),
+                clockShimCounter: chip.hwtimer && chip.hwtimer.controllers.length > 0
+                    ? {
+                        label: chip.hwtimer.controllers[0].nodeLabel,
+                        ...(chip.hwtimer.controllers[0].counterParent ? { parent: chip.hwtimer.controllers[0].counterParent } : {}),
+                    }
+                    : undefined,
                 i2cUsedInstances: scanUsedBusInstances(src, chip.i2c?.controllers, 'i2c'),
                 spiUsedInstances: scanUsedBusInstances(src, chip.spi?.controllers, 'spi'),
                 uartUsedInstances: scanUsedBusInstances(src, chip.uart?.controllers, 'uart'),
@@ -891,10 +986,15 @@ export const Toolchain = {
         // .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) {
+        // Board switches DO need a nuke: `west build`'s --pristine=auto covers
+        // cmake/config churn, not a -b <board> mismatch — west aborts with
+        // "refusing to proceed without --force" and cuttlefish doesn't forward
+        // that flag, so the user would be stuck deleting the dir by hand. The
+        // cache names the board it was configured for (BOARD:STRING); detect the
+        // mismatch and apply west's own suggested remedy automatically.
+        const cachedBoard = cachedBuildBoard(buildDir);
+        const boardChanged = Boolean(cachedBoard && cachedBoard !== board);
+        if (configChanged || boardChanged) {
             try {
                 rmSync(buildDir, { recursive: true, force: true });
             }
@@ -915,7 +1015,7 @@ export const Toolchain = {
             }
         }
         catch { /* no overlay — let Zephyr auto-detect or build without one */ }
-        // Append user cmake args from cuttlefish.config.ts zephyr.cmakeArgs.
+        // Append user cmake args from typecad-hal.config.ts zephyr.cmakeArgs.
         const userCmakeArgs = zc?.cmakeArgs;
         if (userCmakeArgs && userCmakeArgs.length > 0) {
             if (!buildArgs.includes('--'))
@@ -941,36 +1041,39 @@ export const Toolchain = {
         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 + (pristineRetry
-            ? '\n[cuttlefish] dependency cycle detected in the cached build dir — retried with a pristine build'
+            ? '\n[typecad-hal] 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';
-        // After a successful build in gdb mode (--debug on a probe-capable target),
-        // write the VS Code launch.json + tasks.json + gdb-script artifacts so F5
-        // attaches GDB to the chip's debug probe. Non-fatal on failure — a missing
-        // artifact doesn't block the build. Mirrors the deleted framework-esp32
-        // toolchain compile() debug-config wiring.
-        if (result.status === 0 && isGdbDebug) {
+        // After a successful build on a gdb-capable board, keep the VS Code debug
+        // artifacts current: always under --debug, or on a plain build when they
+        // need it (still in create-time starter shape, an outDir rename moved the
+        // app root, or a pre-west self-managed-server entry). Non-fatal on
+        // failure — a missing artifact doesn't block the build.
+        if (result.status === 0 && debugMode === 'gdb') {
             try {
                 const { workspaceRoot, appRel } = resolveDebugLocations(projectRoot);
-                writeDebugConfig({
-                    projectRoot,
-                    workspaceRoot,
-                    appRel,
-                    target: board,
-                    buildDir,
-                    sourceMapPath: join(dirname(o.sourcePath), `${basename(o.sourcePath)}.thcppmap.json`),
-                });
+                if (isGdbDebug
+                    || debugArtifactsNeedRewrite(workspaceRoot, appRel, readRunnersFacts(buildDir)?.gdb?.replace(/\\/g, '/'))) {
+                    writeDebugConfig({
+                        projectRoot,
+                        workspaceRoot,
+                        appRel,
+                        target: board,
+                        buildDir,
+                        sourceMapPath: join(dirname(o.sourcePath), `${basename(o.sourcePath)}.thcppmap.json`),
+                    });
+                }
             }
             catch (e) {
-                console.warn(`[cuttlefish] gdb debug config generation failed: ${e.message}`);
+                console.warn(`[typecad-hal] gdb debug config generation failed: ${e.message}`);
             }
         }
         // As-built snapshot: after a successful build, the resolved devicetree
         // at <buildDir>/zephyr/zephyr.dts carries the board's pinctrl labels —
         // the STABLE name grammar, immune to vendor macro churn. Harvest its
-        // routes into .cuttlefish/as-built.json; the next build's board-module
+        // routes into .typecad-hal/as-built.json; the next build's board-module
         // generation merges them per-pin over the catalog harvest (build wins,
         // silently when they agree). One-build freshness lag on first setup,
         // self-maintaining after. Best-effort — a missing/unparseable artifact
@@ -982,14 +1085,14 @@ export const Toolchain = {
                 const facts = parseZephyrDts(dtsText);
                 const total = facts.adc.length + facts.pwm.length + facts.dac.length;
                 if (total > 0) {
-                    // Write beside the project's board module — the .cuttlefish dir the
+                    // Write beside the project's board module — the .typecad-hal dir the
                     // config loader reads from, discovered by walking up to the
                     // generated board.json (the scaffold root and the config root are
                     // different dirs in the standard layout: src/out vs project root).
-                    let cfDir = join(projectRoot, '.cuttlefish');
+                    let cfDir = join(projectRoot, '.typecad-hal');
                     for (let dir = projectRoot;; dir = dirname(dir)) {
-                        if (existsSync(join(dir, '.cuttlefish', 'board.json'))) {
-                            cfDir = join(dir, '.cuttlefish');
+                        if (existsSync(join(dir, '.typecad-hal', 'board.json'))) {
+                            cfDir = join(dir, '.typecad-hal');
                             break;
                         }
                         const parent = dirname(dir);
@@ -1002,6 +1105,18 @@ export const Toolchain = {
             }
             catch { /* best-effort snapshot — nothing to harvest or unreadable */ }
         }
+        // SBOM stamp: after a successful build, record what the binary is made of
+        // — kernel + linked west modules with commit SHAs + the hashed firmware
+        // artifact (CycloneDX 1.6, next to zephyr.bin) — so `typecad-hal sbom
+        // --check` can gate releases on the record still matching the build
+        // (EU CRA essential-requirements support). Best-effort: a west-list or
+        // hashing failure never blocks the build.
+        if (result.status === 0) {
+            try {
+                stampBuildSbom({ buildDir, board, projectRoot });
+            }
+            catch { /* best-effort SBOM stamp */ }
+        }
         return {
             success: result.status === 0,
             output: header + output,
@@ -1018,6 +1133,22 @@ export const Toolchain = {
         if (!probe.ok) {
             return { success: false, output: `-- west flash: ${probe.error}` };
         }
+        // Flashing over a probe needs it EXCLUSIVE: a debug server still bound to
+        // the gdb port (live session or an orphan whose wrapper died — a VS Code
+        // window reload kills task terminals without killing their children on
+        // Windows) makes openocd fail with LIBUSB_ERROR_ACCESS before any retry
+        // logic can help. Reclaim it up front — it is ours by convention.
+        {
+            const holder = portOwnerPid(DEBUG_SERVER_PORT);
+            if (holder !== undefined && holder !== process.pid) {
+                console.log(`-- west flash: stopping debug server (pid ${holder}) — flashing needs exclusive probe access`);
+                killPidTree(holder);
+                try {
+                    rmSync(join(projectRoot, '.typecad-hal', 'debug-server.pid'), { force: true });
+                }
+                catch { /* already gone */ }
+            }
+        }
         // BOSSA bootloader boards with touch-reset data: open the app's console
         // port at 1200 baud (the firmware's USB shim reboots into the
         // bootloader), wait for the bootloader identity, and flash THAT port.
@@ -1035,7 +1166,7 @@ export const Toolchain = {
         if (uploadRequiresPort(flashRunner) && !flashPort) {
             return {
                 success: false,
-                output: `-- upload requires a port for ${flashRunner} flashing. Set --port <port> on the command line (or the CUTTLEFISH_PORT env var).`,
+                output: `-- upload requires a port for ${flashRunner} flashing. Set --port <port> on the command line (or the TYPECAD_HAL_PORT env var).`,
             };
         }
         if (flashRunner === 'bossac' && flashPort && chip.usb?.touchReset) {
@@ -1172,6 +1303,14 @@ export const Toolchain = {
         // python we spawn resolves pyserial from the same venv). Falls back to the
         // process env when no install is discovered.
         const env = install ? buildEnv(install) : process.env;
+        // Post-flash re-enumeration: the chip resets when `--upload` finishes, the
+        // OS tears the serial device object down and re-creates it, and miniterm's
+        // single open can land inside that window (a FileNotFoundError even though
+        // the board never unplugged). Wait for the port to (re)appear first.
+        if (!waitForSerialPort(py, env, projectRootFromOptions(o), o.port)) {
+            process.exitCode = 1;
+            return;
+        }
         spawnSync(py, ['-m', 'serial.tools.miniterm', o.port, String(baud)], {
             cwd: projectRootFromOptions(o),
             env,
@@ -1206,4 +1345,301 @@ export const Toolchain = {
         });
         spawnSync(inv.command, inv.args, inv.options);
     },
+    debugServer(o, action) {
+        const projectRoot = projectRootFromOptions(o);
+        const buildDir = join(projectRoot, 'build');
+        const pidFile = join(projectRoot, '.typecad-hal', 'debug-server.pid');
+        if (action === 'stop') {
+            stopDebugServer(pidFile);
+            return;
+        }
+        // start: wrap `west debugserver` as a long-running foreground process (the
+        // VS Code background task owns this process; postDebugTask runs `stop`).
+        if (!existsSync(join(buildDir, 'zephyr', 'runners.yaml'))) {
+            console.error(`! No build at ${buildDir} — run 'npm run compile' (or F5's preLaunchTask) first.`);
+            process.exitCode = 1;
+            return;
+        }
+        const stale = readStaleServerPid(pidFile);
+        if (stale !== undefined) {
+            // Already running (pid alive): just re-emit the ready marker so the
+            // task's problem matcher completes immediately.
+            console.log(`[typecad-hal] west debugserver already running (pid ${stale})`);
+            console.log(`TYPECAD_HAL: debug server ready on ${DEBUG_SERVER_PORT}`);
+            return;
+        }
+        try {
+            rmSync(pidFile, { force: true });
+        }
+        catch { /* already gone */ }
+        // A wrapper/west that died without cleanup can leave openocd bound to
+        // the gdb port with a stale pidfile — reclaim it or the new server
+        // cannot bind (and gdb would attach to the orphan).
+        const orphan = portOwnerPid(DEBUG_SERVER_PORT);
+        if (orphan !== undefined && orphan !== process.pid) {
+            console.log(`[typecad-hal] reclaiming orphaned debug server on :${DEBUG_SERVER_PORT} (pid ${orphan})`);
+            killPidTree(orphan);
+        }
+        // Runner + quirk parity with flash (resolveProbeMethod, same as `west
+        // debug`): an explicit zephyr.probe selects the runner; either way, an
+        // srst-based openocd cfg behind an unwired NRST (the probeRunnerQuirks
+        // condition, read from the board's own method data) makes `reset init`
+        // time out — the IDE's post-attach reset would hang the session. Apply
+        // the core-reset override server-side unless the config's runnerArgs
+        // already carry it (the create flow bakes it in).
+        const board = targetFromOptions(o);
+        const chip = chipForBuild(projectRoot, board);
+        const zc = o.zephyrConfig;
+        const probe = resolveProbeMethod(zc, chip, 'debug');
+        // The runner west will actually drive: the explicit choice, else the
+        // board's declared debug-runner default from the build's runners.yaml.
+        const runner = ((probe.ok && probe.runner) || undefined)
+            ?? readRunnersFacts(buildDir)?.debugRunner;
+        const isOcd = runner === undefined || runner === 'openocd' || runner.startsWith('openocd');
+        if (!isOcd) {
+            console.warn(`! debug-server: the IDE wiring (ready marker, quirk args) targets the ` +
+                `openocd runner; this build's debug runner is '${runner}'. Starting it plain — ` +
+                `the F5 session may not connect.`);
+        }
+        const serverArgs = ['debugserver', '-d', buildDir];
+        if (probe.ok) {
+            if (probe.runner)
+                serverArgs.push('--runner', probe.runner);
+            serverArgs.push(...probe.args);
+        }
+        if (isOcd) {
+            serverArgs.push('--gdb-port', String(DEBUG_SERVER_PORT), 
+            // Pinned so the readiness poll below has a deterministic port.
+            '--tcl-port', String(DEBUG_SERVER_TCL_PORT), 
+            // The board's own openocd.cfg may declare gdb-attach/gdb-detach
+            // events (reset-on-attach for standalone sessions). Under an
+            // IDE-managed session a stop event mid-initialization aborts
+            // debugger setup, so neutralize them: west's --cmd-pre-init lands
+            // AFTER the cfg files in the openocd command line, so these win.
+            '--cmd-pre-init', '$_TARGETNAME configure -event gdb-attach {}', '--cmd-pre-init', '$_TARGETNAME configure -event gdb-detach {}');
+            const method = zc?.probe
+                ? chip.probeMethods?.find((m) => m.id === zc?.probe)
+                : chip.probeMethods?.find((m) => m.debug !== false);
+            const cfg = method?.debugCfg ?? [];
+            const srst = cfg.some((l) => /reset_config\s+srst/.test(l));
+            const connectAssert = cfg.some((l) => /connect_assert_srst/.test(l));
+            if (method?.runner === 'openocd' && srst && !connectAssert
+                && !(probe.ok && probe.args.includes('--cmd-pre-init=reset_config none'))) {
+                serverArgs.push('--cmd-pre-init', 'reset_config none');
+            }
+        }
+        const inv = westSpawn(serverArgs, { cwd: projectRoot });
+        const child = spawn(inv.command, inv.args, {
+            ...inv.options,
+            stdio: ['ignore', 'pipe', 'pipe'],
+            // Own process group on POSIX so `stop` can signal the whole tree.
+            ...(process.platform !== 'win32' ? { detached: true } : {}),
+        });
+        // @types/node 26 types ChildProcess's on/once through the internal
+        // InternalEventEmitter base. When `tsc -b` rechecks this package in the
+        // same solution pass that rebuilds its project references, that
+        // inheritance can fail to surface and the spawned child's type loses
+        // .on/.once (TS2339) — while stream types, which COPY the event
+        // signatures, keep working. Subscribe through a structural copy of the
+        // one signature this file needs: the copy-don't-inherit prescription
+        // @types/node itself applies to multi-level emitter classes. The `unknown`
+        // hop keeps the cast legal in both resolution states.
+        const childExit = child;
+        mkdirSync(join(projectRoot, '.typecad-hal'), { recursive: true });
+        writeFileSync(pidFile, String(child.pid), 'utf-8');
+        console.log(`[typecad-hal] starting west debugserver (gdb on localhost:${DEBUG_SERVER_PORT})`);
+        // A reader that goes away (closed task terminal, piped head) must not
+        // take the server down with an EPIPE.
+        process.stdout?.on?.('error', () => { });
+        process.stderr?.on?.('error', () => { });
+        child.stdout?.on('data', (d) => process.stdout.write(d));
+        child.stderr?.on('data', (d) => process.stderr.write(d));
+        // Ready = the TCL port accepts connections. NOT the gdb port: openocd's
+        // gdb server takes ONE client, so a TCP probe there both logs
+        // "attempted 'gdb' connection rejected" and can race the real gdb
+        // connection for the slot. The tcl listener opens at the END of openocd
+        // init (after the gdb listener and the startup halt) — a truer signal —
+        // and probes there are inert.
+        const deadline = Date.now() + DEBUG_SERVER_START_TIMEOUT_MS;
+        const poll = () => {
+            const sock = netConnect(DEBUG_SERVER_TCL_PORT, '127.0.0.1');
+            sock.once('connect', () => {
+                sock.destroy();
+                console.log(`TYPECAD_HAL: debug server ready on ${DEBUG_SERVER_PORT}`);
+            });
+            sock.once('error', () => {
+                sock.destroy();
+                if (child.exitCode !== null)
+                    return; // server died — exit handler reports
+                if (Date.now() > deadline) {
+                    console.error(`! west debugserver did not open :${DEBUG_SERVER_TCL_PORT} within `
+                        + `${DEBUG_SERVER_START_TIMEOUT_MS / 1000}s — see its output above.`);
+                    stopDebugServer(pidFile);
+                    process.exitCode = 1;
+                    return;
+                }
+                setTimeout(poll, 250);
+            });
+        };
+        poll();
+        childExit.on('exit', (code) => {
+            try {
+                rmSync(pidFile, { force: true });
+            }
+            catch { /* already gone */ }
+            // Exit before ready: surface as a task failure (the debugger never
+            // connects and VS Code reports the background task's non-zero exit).
+            if (code !== null && code !== 0)
+                process.exitCode = code;
+        });
+        const forwardSignal = () => {
+            stopDebugServer(pidFile);
+            childExit.once('exit', () => process.exit(0));
+            setTimeout(() => process.exit(0), 1500).unref();
+        };
+        process.on('SIGINT', forwardSignal);
+        process.on('SIGTERM', forwardSignal);
+    },
 };
+/** How long `debug-server start` waits for the gdb port before failing. */
+const DEBUG_SERVER_START_TIMEOUT_MS = 45_000;
+/**
+ * Read the pidfile and return the pid when that process is still alive,
+ * undefined otherwise (no file, dead pid, or unparseable). Best-effort.
+ */
+function readStaleServerPid(pidFile) {
+    try {
+        const pid = Number.parseInt(readFileSync(pidFile, 'utf-8').trim(), 10);
+        if (!Number.isInteger(pid))
+            return undefined;
+        process.kill(pid, 0); // throws ESRCH when dead
+        return pid;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The pid of whatever process is LISTENING on the gdb port — the recovery
+ * path for orphaned servers (the wrapper and west can die while openocd
+ * survives, e.g. a killed task terminal; the pidfile is then stale but the
+ * port stays bound and the next session would attach to the orphan).
+ * Best-effort: netstat on Windows, lsof on POSIX; undefined when the port is
+ * free or the platform tool is unavailable.
+ */
+function portOwnerPid(port) {
+    try {
+        if (process.platform === 'win32') {
+            const out = spawnSync('netstat', ['-ano', '-p', 'tcp'], { encoding: 'utf-8' });
+            if (out.status !== 0)
+                return undefined;
+            for (const line of (out.stdout ?? '').split(/\r?\n/)) {
+                const cols = line.trim().split(/\s+/);
+                if (cols.length >= 5 && cols[3] === 'LISTENING'
+                    && cols[1].endsWith(`:${port}`)) {
+                    const pid = Number.parseInt(cols[4], 10);
+                    if (Number.isInteger(pid))
+                        return pid;
+                }
+            }
+            return undefined;
+        }
+        const out = spawnSync('lsof', ['-ti', `tcp:${port}`], { encoding: 'utf-8' });
+        if (out.status !== 0 || !out.stdout?.trim())
+            return undefined;
+        const pid = Number.parseInt(out.stdout.trim().split(/\s+/)[0], 10);
+        return Number.isInteger(pid) ? pid : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Kill a pid tree (Windows: taskkill /T; POSIX: the process group). */
+function killPidTree(pid) {
+    if (process.platform === 'win32') {
+        // /T: the whole tree (the pid may be the micromamba/west wrapper; openocd
+        // is its grandchild). /F: force — the server has no stdin to close.
+        spawnSync('taskkill', ['/PID', String(pid), '/T', '/F'], { encoding: 'utf-8' });
+    }
+    else {
+        try {
+            process.kill(-pid, 'SIGTERM'); // the detached process group
+        }
+        catch {
+            try {
+                process.kill(pid, 'SIGTERM');
+            }
+            catch { /* already gone */ }
+        }
+    }
+}
+/** Kill the debug server tree (micromamba/west → openocd) and drop the pidfile.
+ *  Falls back to the gdb-port owner when the recorded pid is already dead —
+ *  that orphan would otherwise serve stale sessions forever. */
+function stopDebugServer(pidFile) {
+    const pid = readStaleServerPid(pidFile) ?? portOwnerPid(DEBUG_SERVER_PORT);
+    if (pid === undefined) {
+        try {
+            rmSync(pidFile, { force: true });
+        }
+        catch { /* already gone */ }
+        console.log('[typecad-hal] debug server not running');
+        return;
+    }
+    killPidTree(pid);
+    try {
+        rmSync(pidFile, { force: true });
+    }
+    catch { /* already gone */ }
+    console.log(`[typecad-hal] debug server stopped (pid ${pid})`);
+}
+// -- serial monitor: post-flash re-enumeration wait --------------------------
+/** How long `--monitor` waits for the port to (re)appear after a flash reset. */
+export const MONITOR_PORT_WAIT_MS = 8000;
+/**
+ * The pyserial port wait run before miniterm (argv built by
+ * serialPortWaitArgs). Polls list_ports — never OPENS the port, because
+ * toggling DTR on an open can itself reset some boards — until the device
+ * name matches case-insensitively or the timeout elapses. Exit codes:
+ * 0 port present, 1 timeout (message printed to stderr), 2 pyserial
+ * unavailable (the caller lets miniterm surface the real error instead of
+ * reporting a bogus timeout).
+ */
+const SERIAL_PORT_WAIT_PY = [
+    'import sys, time',
+    'try:',
+    '    from serial.tools import list_ports',
+    'except Exception:',
+    '    sys.exit(2)',
+    'port, timeout = sys.argv[1], float(sys.argv[2])',
+    'def present():',
+    '    return any(d.device.lower() == port.lower() for d in list_ports.comports())',
+    'if not present():',
+    "    print('waiting for %s to re-enumerate (the board resets after flashing)...' % port, flush=True)",
+    '    end = time.time() + timeout',
+    '    while not present():',
+    '        if time.time() >= end:',
+    "            print('%s did not come back within %ds - some boards re-enumerate under a different port name' % (port, int(timeout)), file=sys.stderr, flush=True)",
+    '            sys.exit(1)',
+    '        time.sleep(0.25)',
+].join('\n');
+/** argv for the pyserial port wait — exported for the toolchain unit tests. */
+export function serialPortWaitArgs(port, timeoutMs) {
+    return ['-c', SERIAL_PORT_WAIT_PY, port, String(timeoutMs / 1000)];
+}
+/**
+ * Wait for `port` to be listed by the venv's pyserial before miniterm opens
+ * it once. True = proceed to miniterm (port present, or the wait itself was
+ * best-effort-skipped — a missing python/pyserial lets miniterm show the
+ * underlying failure); false = the port never came back (message printed).
+ */
+function waitForSerialPort(py, env, cwd, port) {
+    const res = spawnSync(py, serialPortWaitArgs(port, MONITOR_PORT_WAIT_MS), {
+        cwd,
+        env,
+        stdio: 'inherit',
+    });
+    if (res.error || res.status === null || res.status === 2)
+        return true;
+    return res.status === 0;
+}