@typecad/framework-zephyr 1.0.0-alpha.8

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

@@ -0,0 +1,82 @@
+export interface DebugConfigOptions {
+    /** Absolute path to the Zephyr project root (contains CMakeLists.txt + src/). */
+    projectRoot: string;
+    /** Absolute path to the workspace root (the cuttlefish config dir — the folder VS Code has open). */
+    workspaceRoot: string;
+    /** The Zephyr app dir relative to the workspace root (e.g. 'src/out'). */
+    sketchRel: string;
+    /** The Zephyr board id (e.g. 'esp32s3_devkitc'). */
+    target: string;
+    /** Absolute path to the Zephyr build dir (<projectRoot>/build) — read for the SDK/GDB path. */
+    buildDir: string;
+    /** Absolute path to the emitted source map (*.thcppmap.json), if any. */
+    sourceMapPath?: string;
+}
+/**
+ * Resolve the GDB binary path for the target from the build cache. Zephyr
+ * records ZEPHYR_SDK_INSTALL_DIR in CMakeCache.txt at configure time, and the
+ * 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).
+ *
+ * Returns the absolute gdb path on success, or undefined (the launch.json then
+ * omits gdbPath and relies on Cortex-Debug's default resolution).
+ */
+export declare function resolveGdbPath(buildDir: string, target: string): string | undefined;
+/**
+ * Resolve the Espressif OpenOCD binary path. The esp32s3 needs the Espressif
+ * OpenOCD fork (openocd-esp32) — not the Zephyr SDK's openocd and not a
+ * generic/GDB-stub build — because only it carries the Xtensa + esp_usb_jtag
+ * support. It is NOT on PATH by default, so Cortex-Debug must be pointed at it
+ * explicitly or it fails with `spawn openocd.exe ENOENT`.
+ *
+ * Discovery order:
+ *   1. ESPRESSIF_TOOLCHAIN_PATH env (the var board.cmake reads) — if set, its
+ *      openocd-esp32/bin/openocd.exe.
+ *   2. The standard ESP-IDF install layout: ~/.espressif/tools/openocd-esp32/
+ *      <version>/openocd-esp32/bin/openocd.exe. Pick the newest version dir.
+ * Returns undefined if not found (the launch.json then omits openOCDPath and
+ * Cortex-Debug falls back to PATH / its openocdPath setting).
+ */
+export declare function resolveOpenOcdPath(): string | undefined;
+/**
+ * Resolve where to write the VS Code debug artifacts and how to express paths
+ * in them.
+ *
+ * VS Code reads `.vscode/` from the folder the user has OPENED — and for a
+ * cuttlefish project that is almost always the **cuttlefish project root**
+ * (the directory containing `cuttlefish.config.ts`), NOT the git repo root.
+ * The toolchain's `projectRoot` is the Zephyr *app* dir (e.g.
+ * `<projectRoot>/src/out`), which sits below the cuttlefish config dir. So we
+ * walk up from `projectRoot` to the nearest `cuttlefish.config.ts` and treat
+ * THAT as the workspace root. This makes F5 work when a user opens the project
+ * folder directly, and keeps launch.json paths relative to it.
+ *
+ * Returns { workspaceRoot, sketchRel } where workspaceRoot is the cuttlefish
+ * project root (the `.vscode/` target) and sketchRel is the Zephyr app dir
+ * (`projectRoot`) relative to it (e.g. 'src/out').
+ */
+export declare function resolveDebugLocations(projectRoot: string): {
+    workspaceRoot: string;
+    sketchRel: string;
+};
+/**
+ * Generate the GDB Python frame-filter that rewrites cuttlefish's hoisted
+ * lambda frame names (`${prefix}_isr_N`) into readable `<lambda> @ file:line`
+ * in the call stack. Only emitted when the source map references `_isr_N`
+ * symbols; otherwise returns null (launch.json omits the `source` initCommand).
+ *
+ * Ported verbatim from the deleted framework-esp32/toolchain/gdb-script.ts —
+ * the filter is cuttlefish-internal (lambda hoisting is framework-agnostic).
+ */
+export declare function generateGdbScript(sourceMapPath?: string): string | null;
+/**
+ * Write all gdb-mode debug artifacts for the given target. Called from the
+ * toolchain compile() after a successful build when debugMode === 'gdb'.
+ *
+ * Writes (all idempotent):
+ *   <workspaceRoot>/.vscode/launch.json   (cortex-debug config)
+ *   <workspaceRoot>/.vscode/tasks.json    (build + flash preLaunch task)
+ *   <projectRoot>/.cuttlefish/openocd.cfg (OpenOCD cfg, adapter speed override)
+ *   <projectRoot>/.cuttlefish/.cuttlefish-gdb.py  (lambda frame filter, conditional)
+ */
+export declare function writeDebugConfig(o: DebugConfigOptions): void;

package/dist/toolchain/debug-config.js

@@ -0,0 +1,359 @@
+// ---------------------------------------------------------------------------
+// debug-config.ts — VS Code / GDB debug artifact generation for `--debug`
+//
+// After a successful gdb-mode build, writes the artifacts that let the user
+// press F5 in VS Code and attach GDB to the running Zephyr target.
+//
+// Uses the cortex-debug extension (NOT the ESP-IDF gdbtarget adapter) so the
+// debug session is self-contained.  cortex-debug starts OpenOCD as a child
+// process via `servertype: "openocd"`; the preLaunch task handles only the
+// build + flash step.  After attach we issue `monitor reset init`, set a
+// temporary hardware breakpoint at setup(), and continue — this ensures the
+// breakpoint is deferred until the bootloader maps the app flash region.
+//
+// All generators are deterministic + idempotent so toggling --debug does not
+// churn the tree.
+// ---------------------------------------------------------------------------
+import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync } from 'node:fs';
+import { join, resolve, dirname, relative } from 'node:path';
+/**
+ * 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
+ * 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).
+ *
+ * Returns the absolute gdb path on success, or undefined (the launch.json then
+ * omits gdbPath and relies on Cortex-Debug's default resolution).
+ */
+export function resolveGdbPath(buildDir, target) {
+    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 (!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).
+    const gdbName = 'xtensa-espressif_esp32s3_zephyr-elf-gdb.exe';
+    const gdbPath = join(sdk, 'xtensa-espressif_esp32s3_zephyr-elf', 'bin', gdbName);
+    return existsSync(gdbPath) ? gdbPath.replace(/\\/g, '/') : undefined;
+}
+/**
+ * Resolve the Espressif OpenOCD binary path. The esp32s3 needs the Espressif
+ * OpenOCD fork (openocd-esp32) — not the Zephyr SDK's openocd and not a
+ * generic/GDB-stub build — because only it carries the Xtensa + esp_usb_jtag
+ * support. It is NOT on PATH by default, so Cortex-Debug must be pointed at it
+ * explicitly or it fails with `spawn openocd.exe ENOENT`.
+ *
+ * Discovery order:
+ *   1. ESPRESSIF_TOOLCHAIN_PATH env (the var board.cmake reads) — if set, its
+ *      openocd-esp32/bin/openocd.exe.
+ *   2. The standard ESP-IDF install layout: ~/.espressif/tools/openocd-esp32/
+ *      <version>/openocd-esp32/bin/openocd.exe. Pick the newest version dir.
+ * Returns undefined if not found (the launch.json then omits openOCDPath and
+ * Cortex-Debug falls back to PATH / its openocdPath setting).
+ */
+export function resolveOpenOcdPath() {
+    const candidates = [];
+    // 1. ESPRESSIF_TOOLCHAIN_PATH env
+    const envPath = process.env.ESPRESSIF_TOOLCHAIN_PATH;
+    if (envPath) {
+        candidates.push(join(envPath, 'openocd-esp32', 'bin', 'openocd.exe'));
+    }
+    // 2. ~/.espressif/tools/openocd-esp32/<version>/openocd-esp32/bin/openocd.exe
+    const home = process.env.USERPROFILE || process.env.HOME;
+    if (home) {
+        const base = join(home, '.espressif', 'tools', 'openocd-esp32');
+        let versions = [];
+        try {
+            versions = readdirSync(base).filter((v) => existsSync(join(base, v, 'openocd-esp32', 'bin', 'openocd.exe')));
+        }
+        catch {
+            // dir absent
+        }
+        // newest version last — sort then reverse so the highest wins on match.
+        versions.sort().reverse();
+        for (const v of versions) {
+            candidates.push(join(base, v, 'openocd-esp32', 'bin', 'openocd.exe'));
+        }
+    }
+    for (const c of candidates) {
+        if (existsSync(c))
+            return resolve(c).replace(/\\/g, '/');
+    }
+    return undefined;
+}
+/**
+ * Resolve where to write the VS Code debug artifacts and how to express paths
+ * in them.
+ *
+ * VS Code reads `.vscode/` from the folder the user has OPENED — and for a
+ * cuttlefish project that is almost always the **cuttlefish project root**
+ * (the directory containing `cuttlefish.config.ts`), NOT the git repo root.
+ * The toolchain's `projectRoot` is the Zephyr *app* dir (e.g.
+ * `<projectRoot>/src/out`), which sits below the cuttlefish config dir. So we
+ * walk up from `projectRoot` to the nearest `cuttlefish.config.ts` and treat
+ * THAT as the workspace root. This makes F5 work when a user opens the project
+ * folder directly, and keeps launch.json paths relative to it.
+ *
+ * Returns { workspaceRoot, sketchRel } where workspaceRoot is the cuttlefish
+ * project root (the `.vscode/` target) and sketchRel is the Zephyr app dir
+ * (`projectRoot`) relative to it (e.g. 'src/out').
+ */
+export function resolveDebugLocations(projectRoot) {
+    // Walk up from the Zephyr app dir to find the cuttlefish project root (the
+    // nearest ancestor containing cuttlefish.config.ts). Fall back to projectRoot
+    // itself if none is found (single-dir project where the app sits at root).
+    let workspaceRoot = resolve(projectRoot);
+    let dir = resolve(projectRoot);
+    for (let i = 0; i < 20; i++) {
+        if (existsSync(join(dir, 'cuttlefish.config.ts'))) {
+            workspaceRoot = dir;
+            break;
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    const sketchRel = relative(workspaceRoot, resolve(projectRoot)).replace(/\\/g, '/');
+    return { workspaceRoot, sketchRel };
+}
+/** Read-merge-write a JSON file, adding/replacing a single config by a key. */
+function mergeJsonArrayEntry(filePath, arrayKey, matchKey, entry) {
+    let doc = {};
+    if (existsSync(filePath)) {
+        try {
+            doc = JSON.parse(readFileSync(filePath, 'utf-8'));
+        }
+        catch {
+            // malformed — start fresh
+        }
+    }
+    const arr = Array.isArray(doc[arrayKey]) ? doc[arrayKey] : [];
+    const idx = arr.findIndex((e) => e[matchKey] === entry[matchKey]);
+    if (idx >= 0)
+        arr[idx] = entry;
+    else
+        arr.push(entry);
+    doc[arrayKey] = arr;
+    mkdirSync(dirname(filePath), { recursive: true });
+    writeFileSync(filePath, JSON.stringify(doc, null, 2) + '\n', 'utf-8');
+}
+/**
+ * Generate the GDB Python frame-filter that rewrites cuttlefish's hoisted
+ * lambda frame names (`${prefix}_isr_N`) into readable `<lambda> @ file:line`
+ * in the call stack. Only emitted when the source map references `_isr_N`
+ * symbols; otherwise returns null (launch.json omits the `source` initCommand).
+ *
+ * Ported verbatim from the deleted framework-esp32/toolchain/gdb-script.ts —
+ * the filter is cuttlefish-internal (lambda hoisting is framework-agnostic).
+ */
+export function generateGdbScript(sourceMapPath) {
+    if (!sourceMapPath || !existsSync(sourceMapPath))
+        return null;
+    let mapText = '';
+    try {
+        mapText = readFileSync(sourceMapPath, 'utf-8');
+    }
+    catch {
+        return null;
+    }
+    // Only emit when the emitted code contains hoisted-lambda symbols.
+    if (!/_isr_\d+/.test(mapText))
+        return null;
+    // A GDB Python frame-filter. Registered via the launch.json initCommand
+    // `source <path>` so GDB auto-loads it on attach.
+    return [
+        '# Auto-generated by @typecad/framework-zephyr. GDB frame-filter that',
+        '# rewrites cuttlefish hoisted-lambda frame names (*_isr_N) into readable',
+        '# <lambda> form so the VS Code call stack is legible.',
+        'import gdb',
+        'import re',
+        '',
+        'class CuttlefishLambdaFilter:',
+        '    def __init__(self):',
+        '        self.name = "cuttlefish_lambda"',
+        '        self.priority = 100',
+        '        self.enabled = True',
+        '',
+        '    def filter(self, frame_iter):',
+        '        isr_re = re.compile(r"(.*)_isr_(\\d+)")',
+        '        return (CuttlefishFrame(f) for f in frame_iter)',
+        '',
+        'class CuttlefishFrame:',
+        '    def __init__(self, frame):',
+        '        self.frame = frame',
+        '    def __getattr__(self, name):',
+        '        val = getattr(self.frame, name)',
+        '        if name == "function":',
+        '            m = isr_re.match(val)',
+        '            if m: return "<lambda>"',
+        '        return val',
+        '',
+        'gdb.frame_filters[CuttlefishLambdaFilter().name] = CuttlefishLambdaFilter()',
+        '',
+    ].join('\n');
+}
+/**
+ * Build the cortex-debug launch.json config for an ESP32-S3 (built-in USB-JTAG).
+ * `openOcdCfgRel` is the workspace-relative path to the generated
+ * .cuttlefish/openocd.cfg, passed to cortex-debug's configFiles.
+ */
+function buildLaunchConfig(o, gdbScriptRel, openOcdCfgRel) {
+    // The ELF is at <projectRoot>/build/zephyr/zephyr.elf (Zephyr's standard
+    // build output). cortex-debug uses `executable` (not `program`).
+    const executable = `\${workspaceFolder}/${o.sketchRel}/build/zephyr/zephyr.elf`;
+    // OpenOCD cfg relative to the workspace root so cortex-debug can pass it
+    // via the -f flag.  Must be a list; cortex-debug prepends -f per entry.
+    const configFiles = [`\${workspaceFolder}/${openOcdCfgRel}`];
+    // GDB path resolved from the Zephyr SDK build cache (CMakeCache.txt).
+    const gdbPath = resolveGdbPath(o.buildDir, o.target);
+    // OpenOCD binary path — the Espressif fork (openocd-esp32) is required for
+    // the esp_usb_jtag adapter.  cortex-debug's `serverpath` tells it where to
+    // find the binary (not on PATH by default).
+    const openocdPath = resolveOpenOcdPath();
+    // Post-attach commands executed after GDB connects to the OpenOCD gdbserver.
+    //   set mem inaccessible-by-default off — suppresses "Cannot access memory"
+    //     errors caused by overlapping Xtensa memory regions (flash-mapped
+    //     0x4200xxxx isn't accessible until the bootloader runs).
+    //   mem 0x42000000 0x44000000 ro cache — tells GDB the app flash region IS
+    //     read-only so -break-insert uses hw breakpoints, not sw breakpoints
+    //     (which would fail with "Cannot access memory at 0x4200xxxx").
+    //   monitor reset init  — reset target + halt (bootloader maps flash)
+    //   thb setup           — temporary HW breakpoint at setup()
+    //   c                   — continue; bootloader maps flash, breaks at setup()
+    //
+    // Paths use forward slashes — ${workspaceFolder} on Windows produces
+    // backslashes that GDB interprets as escape sequences (\t → tab, etc.).
+    const ws = o.workspaceRoot.replace(/\\/g, '/');
+    const postAttachCommands = [
+        `set directories ${ws}`,
+        'set remote hardware-watchpoint-limit 2',
+        'set remote hardware-breakpoint-limit 2',
+        'set mem inaccessible-by-default off',
+        'mem 0x42000000 0x44000000 ro cache',
+        'monitor reset init',
+        'thb setup',
+        'c',
+    ];
+    if (gdbScriptRel) {
+        postAttachCommands.splice(1, 0, `source ${ws}/${gdbScriptRel}`);
+    }
+    const cfg = {
+        name: 'TypeCAD Debug (Zephyr, ESP32-S3)',
+        type: 'cortex-debug',
+        // Attach mode: no download (the ELF is already flashed). The server
+        // controller's attachCommands() just halts the target, then our
+        // postAttachCommands reset it, set a HW breakpoint at setup(), and
+        // continue.  HW breakpoints use debug registers and work before the
+        // bootloader maps the app flash region.
+        request: 'attach',
+        cwd: '${workspaceFolder}',
+        executable,
+        servertype: 'openocd',
+        configFiles,
+        interface: 'jtag',
+        ...(gdbPath ? { gdbPath } : {}),
+        ...(openocdPath ? { serverpath: openocdPath } : {}),
+        postAttachCommands,
+        preLaunchTask: 'cuttlefish: build + flash (debug)',
+    };
+    // openOcdCfgRel is consumed by configFiles above. Referenced here only to
+    // keep the signature honest.
+    void openOcdCfgRel;
+    return cfg;
+}
+/**
+ * Build the tasks.json entry: rebuild + flash only.  cortex-debug starts
+ * OpenOCD as a child process (servertype: "openocd"), so the preLaunch task
+ * just needs to build and upload — no isBackground / OpenOCD wrapping.
+ */
+function buildTask(o) {
+    return {
+        label: 'cuttlefish: build + flash (debug)',
+        type: 'shell',
+        command: 'npx cuttlefish build --compile --upload --debug',
+        options: { cwd: `\${workspaceFolder}/${o.sketchRel}` },
+        group: { kind: 'build', isDefault: false },
+        problemMatcher: [],
+    };
+}
+/**
+ * The adapter speed the S3's built-in USB-Serial-JTAG runs stably at.
+ *
+ * The interface cfg (esp_usb_jtag.cfg) defaults to 40000 (40 MHz), the chip
+ * max. The USB-Serial-JTAG peripheral is a software bitq adapter that bit-bangs
+ * JTAG over USB bulk transfers; at 40 MHz it can't keep up, drops transfers
+ * (LIBUSB_ERROR_IO / "missing data from bitq interface"), and the reset/halt
+ * sequence silently fails — leaving the target running with no breakpoint set
+ * (the "debugger starts but never stops / buttons don't work" symptom).
+ *
+ * 4000 (4 MHz) is the empirically-stable speed for this peripheral.
+ */
+const OPENOCD_ADAPTER_SPEED = 4000;
+/**
+ * Build the OpenOCD cfg content. Sources the board's own openocd.cfg (which
+ * sets ESP_RTOS Zephyr + ESP_ONLYCPU + the esp_usb_jtag driver + the esp32s3
+ * target) then overrides the adapter speed AFTER the driver loads — the order
+ * that a bare `-c "adapter speed N"` cannot guarantee (OpenOCD applies -c args
+ * in command-line order relative to -f, and Cortex-Debug injects its own
+ * helper/RTOS tcl, so the override can land before the driver exists or be
+ * re-defaulted). Putting it in the cfg, after the source, is deterministic.
+ */
+function buildOpenOcdCfg() {
+    return [
+        '# Auto-generated by @typecad/framework-zephyr. Do not edit — regenerate',
+        '# with `cuttlefish build --debug`. Sources the board cfg (which loads the',
+        '# esp_usb_jtag adapter driver + esp32s3 target + ESP_RTOS Zephyr) then',
+        '# overrides the adapter speed to a USB-JTAG-stable value AFTER the driver',
+        '# is loaded. See debug-config.ts for the rationale.',
+        'source [find board/esp32s3-builtin.cfg]',
+        `adapter speed ${OPENOCD_ADAPTER_SPEED}`,
+        '',
+    ].join('\n');
+}
+/**
+ * Write all gdb-mode debug artifacts for the given target. Called from the
+ * toolchain compile() after a successful build when debugMode === 'gdb'.
+ *
+ * Writes (all idempotent):
+ *   <workspaceRoot>/.vscode/launch.json   (cortex-debug config)
+ *   <workspaceRoot>/.vscode/tasks.json    (build + flash preLaunch task)
+ *   <projectRoot>/.cuttlefish/openocd.cfg (OpenOCD cfg, adapter speed override)
+ *   <projectRoot>/.cuttlefish/.cuttlefish-gdb.py  (lambda frame filter, conditional)
+ */
+export function writeDebugConfig(o) {
+    const vscodeDir = join(o.workspaceRoot, '.vscode');
+    const cuttlefishDir = join(o.projectRoot, '.cuttlefish');
+    mkdirSync(cuttlefishDir, { recursive: true });
+    // openocd.cfg — written first so its relative path can be wired into the
+    // cortex-debug configFiles.  cortex-debug starts OpenOCD as a child process
+    // and passes this file via -f.
+    const openOcdCfgPath = join(cuttlefishDir, 'openocd.cfg');
+    writeFileSync(openOcdCfgPath, buildOpenOcdCfg(), 'utf-8');
+    const openOcdCfgRel = `${o.sketchRel}/.cuttlefish/openocd.cfg`;
+    // launch.json — merge the cortex-debug config by name.
+    const gdbScript = generateGdbScript(o.sourceMapPath);
+    let gdbScriptRel;
+    if (gdbScript) {
+        const scriptPath = join(cuttlefishDir, '.cuttlefish-gdb.py');
+        writeFileSync(scriptPath, gdbScript, 'utf-8');
+        gdbScriptRel = `${o.sketchRel}/.cuttlefish/.cuttlefish-gdb.py`;
+    }
+    const launchConfig = buildLaunchConfig(o, gdbScriptRel, openOcdCfgRel);
+    mergeJsonArrayEntry(join(vscodeDir, 'launch.json'), 'configurations', 'name', launchConfig);
+    // tasks.json — merge the build+flash task by label.  OpenOCD is managed by
+    // cortex-debug so the task is a simple synchronous build step.
+    const task = buildTask(o);
+    mergeJsonArrayEntry(join(vscodeDir, 'tasks.json'), 'tasks', 'label', task);
+}

package/dist/toolchain/index.d.ts

@@ -0,0 +1,73 @@
+import type { ToolchainOptions, CompileResult, UploadResult } from '@typecad/cuttlefish/api/shared';
+/**
+ * Derive the Zephyr project root from the cuttlefish-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/`).
+ * For Zephyr, the project root is the parent of `src/` — one level above
+ * `outputDir`. Detect that shape and adjust; otherwise fall back to `outputDir`.
+ */
+export declare function projectRootFromOptions(o: ToolchainOptions): string;
+/**
+ * Build the `west flash` argument list for a board.
+ *
+ * Runner selection: each board's board.cmake declares a sensible default flash
+ * runner for its hardware (xiao_ble → nrfutil, esp32* → esptool), and `west
+ * flash` resolves it automatically. The framework only intervenes where the
+ * board default needs an argument it can't infer:
+ *   - An explicit `zephyr.runner` (from cuttlefish.config.ts) always wins.
+ *   - ESP32 boards forward the port via `--esp-device` (esptool reads the
+ *     device from it); board.cmake still picks the runner.
+ *   - Every other board trusts the board.cmake default. Previously this forced
+ *     `--runner nrfjprog` for every non-ESP32 target, which broke boards whose
+ *     default is not nrfjprog (xiao_ble defaults to nrfutil) and required
+ *     Nordic J-Link tools that a USB-bootloader board does not have.
+ *
+ * Exported (pure) so the runner-selection contract is unit-testable without
+ * spawning west.
+ */
+export declare function buildFlashArgs(buildDir: string, board: string, userRunner: string | undefined, port: string | undefined): string[];
+/**
+ * Classify a `west flash` result as success/failure.
+ *
+ * west's exit status is authoritative except for one known race in the uf2
+ * runner on Windows: the UF2 bootloader reboots to run new firmware the instant
+ * the file copy completes, unmounting the USB-MSC drive before `shutil.copy`'s
+ * trailing `copymode`/chmod runs. That raises `OSError: [WinError 433] A
+ * device which does not exist was specified` and makes west exit non-zero —
+ * even though the firmware copied and flashed correctly (the LED blinks).
+ *
+ * The copy starting is logged ("Copying UF2 file to '<drive>'"); WinError 433
+ * during `copymode` after that point proves the data write finished and the
+ * drive only vanished on the metadata step. Treat that exact signature as
+ * success so the upload isn't reported as a failure. Genuine uf2 failures
+ * (no partition found, write errors before the copy) still surface as failures.
+ *
+ * Exported (pure) so the classification is unit-testable without spawning west.
+ */
+export declare function classifyUploadResult(runner: string | undefined, status: number | null, output: string): boolean;
+/**
+ * Cleanse the `west flash` output shown to the user.
+ *
+ * When classifyUploadResult has decided a non-zero west exit was the benign UF2
+ * race (firmware copied, drive unmounted on the trailing chmod), the raw output
+ * is a wall of Python traceback that reads like a hard failure. Drop everything
+ * after the "Copying UF2 file to" line — i.e. the entire traceback — so a
+ * successful flash reads as a success (the framework's ✓ Done follows). Non-race
+ * output is returned untouched; genuine errors stay fully visible for diagnosis.
+ *
+ * Exported (pure) so the cleansing is unit-testable without spawning west.
+ */
+export declare function cleanseUploadOutput(runner: string | undefined, status: number | null, output: string): string;
+/**
+ * FrameworkToolchain for Zephyr. Spec §3.5 (mirror of the ESP-IDF toolchain).
+ * The target board is carried via frameworkData.buildTarget; scaffolding
+ * happens at compile time when the target is known.
+ */
+export declare const Toolchain: {
+    prepare(outputDir: string, entryPoint: string): void;
+    compile(o: ToolchainOptions): CompileResult;
+    upload(o: ToolchainOptions): UploadResult;
+    monitor(o: ToolchainOptions): void;
+    debug(o: ToolchainOptions): void;
+};