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

package/dist/toolchain/debug-config.js

@@ -8,7 +8,7 @@
 // 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
+// temporary hardware breakpoint at main(), 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
@@ -17,6 +17,9 @@
 import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync } from 'node:fs';
 import { join, resolve, dirname, relative } from 'node:path';
 import { ZephyrStrategy } from '../strategy.js';
+import { resolveChipFromBoard } from '../chips/resolve.js';
+import { resolveProbeMethod } from './index.js';
+import { loadCuttlefishConfig } from '@typecad/cuttlefish/config-loader';
 /**
  * Resolve the GDB binary path for the target from the build cache, falling
  * back to a filesystem scan of known Zephyr SDK locations when no build
@@ -29,14 +32,13 @@ import { ZephyrStrategy } from '../strategy.js';
  * omits gdbPath and relies on Cortex-Debug's default resolution).
  */
 export function resolveGdbPath(buildDir, target) {
-    void target; // toolchain dir is esp32s3-specific today; see gdbPathFromSdkRoot
     const cachePath = join(buildDir, 'CMakeCache.txt');
     if (existsSync(cachePath)) {
         try {
             const cache = readFileSync(cachePath, 'utf-8');
             const m = cache.match(/^ZEPHYR_SDK_INSTALL_DIR:PATH=(.+)$/m);
             if (m) {
-                const fromCache = gdbPathFromSdkRoot(m[1].trim());
+                const fromCache = gdbPathFromSdkRoot(m[1].trim(), target);
                 if (fromCache)
                     return fromCache;
             }
@@ -47,17 +49,23 @@ export function resolveGdbPath(buildDir, target) {
     }
     // No build dir yet (project just created): probe known SDK locations.
     for (const sdkRoot of discoverZephyrSdkRoots()) {
-        const p = gdbPathFromSdkRoot(sdkRoot);
+        const p = gdbPathFromSdkRoot(sdkRoot, target);
         if (p)
             return p;
     }
     return undefined;
 }
-/** The esp32s3 xtensa GDB location inside a Zephyr SDK root (verified against
- *  zephyr-sdk-0.17.4). Returns a forward-slash absolute path or undefined. */
-export function gdbPathFromSdkRoot(sdkRoot) {
-    const gdbName = 'xtensa-espressif_esp32s3_zephyr-elf-gdb.exe';
-    const gdbPath = join(sdkRoot, 'xtensa-espressif_esp32s3_zephyr-elf', 'bin', gdbName);
+/** The GDB location inside a Zephyr SDK root, per target architecture:
+ *  ARM boards use the arm-zephyr-eabi toolchain (verified against
+ *  zephyr-sdk-0.17.4), Espressif the xtensa-espressif_esp32s3_zephyr-elf one.
+ *  Returns a forward-slash absolute path or undefined. */
+export function gdbPathFromSdkRoot(sdkRoot, target) {
+    // No target given (legacy callers/tests): the historical Espresif default.
+    const boardId = (target ?? '').split('/')[0];
+    const isArm = boardId.length > 0 && !boardId.startsWith('esp32');
+    const toolchainDir = isArm ? 'arm-zephyr-eabi' : 'xtensa-espressif_esp32s3_zephyr-elf';
+    const gdbName = isArm ? 'arm-zephyr-eabi-gdb.exe' : 'xtensa-espressif_esp32s3_zephyr-elf-gdb.exe';
+    const gdbPath = join(sdkRoot, toolchainDir, 'bin', gdbName);
     return existsSync(gdbPath) ? gdbPath.replace(/\\/g, '/') : undefined;
 }
 /** Compare two dotted version strings numerically (0.17.10 > 0.17.4). */
@@ -76,7 +84,7 @@ function compareSdkVersions(a, b) {
  * Probe the well-known Zephyr SDK install locations, newest version first:
  *   1. $ZEPHYR_SDK_INSTALL_DIR (the var board.cmake reads)
  *   2. <MAMBA_ROOT_PREFIX | ~/micromamba>/zephyr-sdk/zephyr-sdk-<ver> — the
- *      @typecad/zephyr-installer layout
+ *      the bundled Zephyr installer layout
  *   3. ~/zephyr-sdk-<ver> — the standalone download layout
  *
  * Only roots that actually contain the esp32s3 GDB are useful to callers;
@@ -116,44 +124,59 @@ export function discoverZephyrSdkRoots(opts) {
     return roots.filter((r, i) => roots.indexOf(r) === i);
 }
 /**
- * Resolve the Espressif OpenOCD binary path. The esp32s3 needs the Espressif
- * OpenOCD fork (openocd-esp32) — not the Zephyr SDK's openocd and not a
+ * Resolve the 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`.
+ * support. ARM targets prefer the Zephyr SDK's own openocd (it ships the
+ * interface/target cfgs boards reference); the Espressif fork is only
+ * consulted for esp32 targets.
  *
  * Discovery order:
- *   1. ESPRESSIF_TOOLCHAIN_PATH env (the var board.cmake reads) — if set, its
- *      openocd-esp32/bin/openocd.exe.
+ *   1. ESPRESSIF_TOOLCHAIN_PATH env (the var board.cmake reads) — esp32
+ *      targets; 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.
+ *      <version>/openocd-esp32/bin/openocd.exe (esp32 targets; newest first).
+ *   3. A Zephyr SDK root (discoverZephyrSdkRoots) — its
+ *      tools/opt/openocd/bin/openocd(.exe), any target.
  * Returns undefined if not found (the launch.json then omits openOCDPath and
  * Cortex-Debug falls back to PATH / its openocdPath setting).
  */
-export function resolveOpenOcdPath() {
+export function resolveOpenOcdPath(target) {
+    const isEsp32Target = (target ?? '').split('/')[0].startsWith('esp32');
     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
+    if (isEsp32Target) {
+        // 1. ESPRESSIF_TOOLCHAIN_PATH env
+        const envPath = process.env.ESPRESSIF_TOOLCHAIN_PATH;
+        if (envPath) {
+            candidates.push(join(envPath, 'openocd-esp32', 'bin', 'openocd.exe'));
         }
-        // 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'));
+        // 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'));
+            }
         }
     }
+    // 3. The Zephyr SDK's openocd (ARM targets' interface/target cfgs ship
+    // with it — interface/stlink-dap.cfg, target/stm32f4x.cfg, ...). Layout
+    // differs by SDK generation: 1.0.x hosttools/openocd, 0.17.x
+    // tools/opt/openocd (when present).
+    const exe = process.platform === 'win32' ? 'openocd.exe' : 'openocd';
+    for (const sdkRoot of discoverZephyrSdkRoots()) {
+        candidates.push(join(sdkRoot, 'hosttools', 'openocd', 'bin', exe));
+        candidates.push(join(sdkRoot, 'tools', 'opt', 'openocd', 'bin', exe));
+    }
     for (const c of candidates) {
         if (existsSync(c))
             return resolve(c).replace(/\\/g, '/');
@@ -173,8 +196,8 @@ export function resolveOpenOcdPath() {
  * 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
+ * Returns { workspaceRoot, appRel } where workspaceRoot is the cuttlefish
+ * project root (the `.vscode/` target) and appRel is the Zephyr app dir
  * (`projectRoot`) relative to it (e.g. 'src/out').
  */
 export function resolveDebugLocations(projectRoot) {
@@ -193,8 +216,8 @@ export function resolveDebugLocations(projectRoot) {
             break;
         dir = parent;
     }
-    const sketchRel = relative(workspaceRoot, resolve(projectRoot)).replace(/\\/g, '/');
-    return { workspaceRoot, sketchRel };
+    const appRel = relative(workspaceRoot, resolve(projectRoot)).replace(/\\/g, '/');
+    return { workspaceRoot, appRel };
 }
 /** Read-merge-write a JSON file, adding/replacing a single config by a key. */
 function mergeJsonArrayEntry(filePath, arrayKey, matchKey, entry) {
@@ -277,10 +300,10 @@ export function generateGdbScript(sourceMapPath) {
  * `openOcdCfgRel` is the workspace-relative path to the generated
  * .cuttlefish/openocd.cfg, passed to cortex-debug's configFiles.
  */
-function buildLaunchConfig(o, gdbScriptRel, openOcdCfgRel) {
+function buildLaunchConfig(o, gdbScriptRel, openOcdCfgRel, method) {
     // 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`;
+    const executable = `\${workspaceFolder}/${o.appRel}/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}`];
@@ -289,7 +312,7 @@ function buildLaunchConfig(o, gdbScriptRel, openOcdCfgRel) {
     // 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();
+    const openocdPath = resolveOpenOcdPath(o.target);
     // 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
@@ -298,41 +321,62 @@ function buildLaunchConfig(o, gdbScriptRel, openOcdCfgRel) {
     //     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()
+    //   thb main            — temporary HW breakpoint at main()
+    //   c                   — continue; bootloader maps flash, breaks at main()
+    //
+    // The trailing `c` is ESP32-only. On instant-reset ARM targets the
+    // thb-main stop lands within milliseconds — WHILE cortex-debug is still
+    // chewing through this command list — and a stop event mid-initialization
+    // leaves the session half-started (toolbar never enables, user breakpoints
+    // never bind). The ESP32's bootloader takes hundreds of milliseconds, so
+    // its stop safely arrives after init completes. ARM keeps the pending
+    // thb (the first user Continue stops at main()) but hands the run/stop
+    // transition to cortex-debug.
     //
     // Paths use forward slashes — ${workspaceFolder} on Windows produces
     // backslashes that GDB interprets as escape sequences (\t → tab, etc.).
     const ws = o.workspaceRoot.replace(/\\/g, '/');
+    // The Xtensa flash-mapping commands are ESP32-specific (app flash isn't
+    // readable until the bootloader maps it); ARM targets drop them.
+    const isEsp32Target = o.target.split('/')[0].startsWith('esp32');
     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',
+        ...(isEsp32Target ? [
+            'set mem inaccessible-by-default off',
+            'mem 0x42000000 0x44000000 ro cache',
+        ] : []),
         'monitor reset init',
-        'thb setup',
-        'c',
+        'thb main',
+        ...(isEsp32Target ? ['c'] : []),
     ];
     if (gdbScriptRel) {
         postAttachCommands.splice(1, 0, `source ${ws}/${gdbScriptRel}`);
     }
+    // Probe-method-driven server shape: jlink-runner methods use cortex-debug's
+    // jlink server (needs the device name from the board table); openocd-runner
+    // methods keep the openocd server with the generated cfg file. Without a
+    // method (ESP32 builtin-JTAG targets), the historical default applies.
+    const servertype = method?.runner === 'jlink' ? 'jlink' : 'openocd';
+    const isEsp32 = o.target.split('/')[0].startsWith('esp32');
     const cfg = {
-        name: 'TypeCAD Debug (Zephyr, ESP32-S3)',
+        name: `TypeCAD Debug (Zephyr, ${o.target.split('/')[0]})`,
         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
+        // postAttachCommands reset it, set a HW breakpoint at main(), 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',
+        servertype,
+        ...(servertype === 'openocd' ? { configFiles } : {}),
+        ...(method?.debugDevice ? { device: method.debugDevice } : {}),
+        interface: method?.debugInterface ?? (isEsp32 ? 'jtag' : 'swd'),
         ...(gdbPath ? { gdbPath } : {}),
-        ...(openocdPath ? { serverpath: openocdPath } : {}),
+        ...(servertype === 'openocd' && openocdPath ? { serverpath: openocdPath } : {}),
         postAttachCommands,
         preLaunchTask: 'cuttlefish: build + flash (debug)',
     };
@@ -351,7 +395,7 @@ function buildTask(o) {
         label: 'cuttlefish: build + flash (debug)',
         type: 'shell',
         command: 'npx cuttlefish build --compile --upload --debug',
-        options: { cwd: `\${workspaceFolder}/${o.sketchRel}` },
+        options: { cwd: `\${workspaceFolder}/${o.appRel}` },
         group: { kind: 'build', isDefault: false },
         problemMatcher: [],
     };
@@ -378,13 +422,77 @@ const OPENOCD_ADAPTER_SPEED = 4000;
  * 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 [
+/**
+ * Drop the gdb-attach/gdb-detach target-event blocks from a cfg line list.
+ * Board cfgs use them for standalone openocd sessions (reset on attach,
+ * resume on detach), but under VS Code they fire DURING cortex-debug's
+ * initialization — the unexpected stop event aborts the session setup
+ * ("Program stopped, probably due to a reset and/or halt issued by
+ * debugger") and the toolbar never enables. The IDE owns the lifecycle.
+ */
+function stripGdbEventBlocks(lines) {
+    const out = [];
+    let skipping = false;
+    let depth = 0;
+    for (const line of lines) {
+        if (!skipping && /configure\s+-event\s+gdb-(attach|detach)/.test(line)) {
+            skipping = true;
+            depth = 0;
+        }
+        if (skipping) {
+            depth += (line.match(/\{/g) ?? []).length - (line.match(/\}/g) ?? []).length;
+            if (depth <= 0 && (line.includes('}') || !line.includes('{')))
+                skipping = false;
+            continue;
+        }
+        out.push(line);
+    }
+    return out;
+}
+function buildOpenOcdCfg(method, target) {
+    const header = [
         '# 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.',
+        '# with `cuttlefish build --debug`.',
+    ];
+    // Zephyr RTOS awareness (thread names in the call stack) — appended after
+    // the target source on ARM targets; the ESP32 board cfgs already carry
+    // ESP_RTOS Zephyr.
+    const isEsp32 = (target ?? '').split('/')[0].startsWith('esp32');
+    const rtosLine = isEsp32 ? [] : ['$_TARGETNAME configure -rtos Zephyr'];
+    if (method?.debugCfgSource && method.debugCfgSource.length > 0) {
+        // Probe-method-driven config: the board package's verified interface +
+        // target sources, then the method's quirk lines (e.g. reset_config for an
+        // unwired SRST) — the cfg-file form of the west runner args.
+        return [
+            ...header,
+            `# Probe method '${method.id}' — from the board package's probeMethods table.`,
+            ...method.debugCfgSource.map((src) => `source [find ${src}]`),
+            ...stripGdbEventBlocks(method.debugCfg ?? []),
+            ...rtosLine,
+            '',
+        ].join('\n');
+    }
+    // Pack-derived methods (the board's own support/openocd.cfg, extracted by
+    // the board data pack) carry complete cfg lines — including their
+    // `source [find ...]` directives — verbatim in file order, minus the
+    // gdb-attach/detach events (IDE-managed lifecycle; see stripGdbEventBlocks).
+    if (method?.debugCfg && method.debugCfg.length > 0) {
+        return [
+            ...header,
+            `# Probe method '${method.id}' — the board's own support/openocd.cfg,`,
+            `# extracted by the board data pack (gdb-attach/detach events removed —`,
+            `# the IDE owns the session lifecycle).`,
+            ...stripGdbEventBlocks(method.debugCfg),
+            ...rtosLine,
+            '',
+        ].join('\n');
+    }
+    return [
+        ...header,
+        '# 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}`,
         '',
@@ -400,25 +508,57 @@ function buildOpenOcdCfg() {
  *   <projectRoot>/.cuttlefish/openocd.cfg (OpenOCD cfg, adapter speed override)
  *   <projectRoot>/.cuttlefish/.cuttlefish-gdb.py  (lambda frame filter, conditional)
  */
+/**
+ * Resolve the debug-side probe method for a project: the board constants the
+ * transpile persists + the workspace config's zephyr.probe selection.
+ * Returns the method object (for cfg/servertype data) or undefined — ESP32
+ * targets and boards without tables fall back to the framework's default
+ * (esp_usb_jtag openocd) behavior.
+ */
+function resolveDebugProbeMethod(projectRoot, workspaceRoot) {
+    try {
+        const bcPath = [
+            join(projectRoot, 'src', 'board-constants.json'),
+            join(projectRoot, 'board-constants.json'),
+        ].find((p) => existsSync(p));
+        if (!bcPath)
+            return undefined;
+        const raw = JSON.parse(readFileSync(bcPath, 'utf8'));
+        const chip = resolveChipFromBoard(new Map(Object.entries(raw)));
+        if (!chip)
+            return undefined;
+        const zc = loadCuttlefishConfig(workspaceRoot)?.zephyrConfig;
+        const probe = resolveProbeMethod(zc, chip, 'debug');
+        if (!probe.ok)
+            return undefined;
+        return chip.probeMethods?.find((m) => m.id === zc?.probe);
+    }
+    catch {
+        return undefined;
+    }
+}
 export function writeDebugConfig(o) {
     const vscodeDir = join(o.workspaceRoot, '.vscode');
     const cuttlefishDir = join(o.projectRoot, '.cuttlefish');
     mkdirSync(cuttlefishDir, { recursive: true });
+    // The selected probe method (if any) drives the debug server shape:
+    // openocd cfg source/quirks, cortex-debug servertype, wire interface.
+    const method = resolveDebugProbeMethod(o.projectRoot, o.workspaceRoot);
     // 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`;
+    writeFileSync(openOcdCfgPath, buildOpenOcdCfg(method, o.target), 'utf-8');
+    const openOcdCfgRel = `${o.appRel}/.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`;
+        gdbScriptRel = `${o.appRel}/.cuttlefish/.cuttlefish-gdb.py`;
     }
-    const launchConfig = buildLaunchConfig(o, gdbScriptRel, openOcdCfgRel);
+    const launchConfig = buildLaunchConfig(o, gdbScriptRel, openOcdCfgRel, method);
     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.
@@ -431,9 +571,9 @@ export function writeDebugConfig(o) {
  * the CLI resolves output.outDir against the ENTRY's directory (cli.ts), so
  * the emitted app root — and therefore the ELF, build dir, and .cuttlefish/
  * debug artifacts — always lands at `src/out`. Keep in sync with
- * generateProjectConfig in @typecad/cuttlefish create/init-templates.ts.
+ * generateProjectConfig in @typecad/cuttlefish create/templates.ts.
  */
-const STARTER_SKETCH_REL = 'src/out';
+const STARTER_APP_REL = 'src/out';
 /**
  * Create-time starter debug artifacts. Called by the cuttlefish `create` flow
  * (via the package's `writeProjectDebugArtifacts` export) so a fresh project
@@ -453,11 +593,11 @@ export function writeProjectDebugArtifacts(o) {
     if (new ZephyrStrategy().debugMode(o.buildTarget) !== 'gdb')
         return [];
     const workspaceRoot = resolve(o.workspaceRoot);
-    const projectRoot = join(workspaceRoot, STARTER_SKETCH_REL);
+    const projectRoot = join(workspaceRoot, STARTER_APP_REL);
     writeDebugConfig({
         projectRoot,
         workspaceRoot,
-        sketchRel: STARTER_SKETCH_REL,
+        appRel: STARTER_APP_REL,
         target: o.buildTarget ?? '',
         // No build dir exists yet — resolveGdbPath falls back to probing known
         // Zephyr SDK locations so gdbPath is still filled in when possible.
@@ -466,6 +606,6 @@ export function writeProjectDebugArtifacts(o) {
     return [
         '.vscode/launch.json',
         '.vscode/tasks.json',
-        `${STARTER_SKETCH_REL}/.cuttlefish/openocd.cfg`,
+        `${STARTER_APP_REL}/.cuttlefish/openocd.cfg`,
     ];
 }

package/dist/toolchain/env-check.d.ts

@@ -2,7 +2,7 @@ import { type WestInstall } from './west-discover.js';
 import { type CompatStatus } from './compat.js';
 /**
  * Raw west facts gathered from discovery + a `west --version` probe. Mirrors
- * ArduinoCliProbeData: `westFound` is true when a usable west install was
+ * probe data: `westFound` is true when a usable west install was
  * discovered (discovery itself probes responsiveness).
  */
 export interface WestProbeData {
@@ -16,8 +16,8 @@ export interface WestProbeData {
     zephyrBase: string | undefined;
 }
 /**
- * Test-injection seam for checkZephyrEnv. Mirrors Arduino's
- * CheckArduinoEnvOptions.fakeProbe so tests never spawn a real west/python.
+ * Test-injection seam for checkZephyrEnv. Mirrors the
+ * fakeProbe option so tests never spawn a real west/python.
  */
 export interface CheckZephyrEnvOptions {
     /** FOR TESTS ONLY: skip the real probe and use this data directly. */
@@ -84,7 +84,7 @@ export declare function boardExistsInCheckout(boardId: string, zephyrBase: strin
  * checkout. Reports what (if anything) is wrong.
  *
  * - If `buildTarget` is undefined/empty, the board check is skipped (not a
- *   failure), mirroring Arduino's no-FQBN path.
+ *   failure), mirroring the no-build-target path.
  * - Never installs anything. Never mutates the user environment.
  * - Never throws — always returns a result. Callers decide how to react.
  *

package/dist/toolchain/env-check.js

@@ -1,15 +1,15 @@
 // ---------------------------------------------------------------------------
 // Zephyr environment check — the shared detection behind `cuttlefish doctor`.
 //
-// Mirrors @typecad/arduino-cli's checkArduinoEnv(): gather the impure
+// Zephyr environment check: gather the impure
 // environment facts once (west presence + version, Zephyr version, board
 // existence), then reduce them to a structured result the doctor (and, later,
 // the build/test gates) can present uniformly. The check is side-effect-free
 // and never throws — it never installs or mutates anything.
 //
-// Two parity checks vs. framework-arduino's doctor:
+// Two checks (mirroring the doctor contract):
 //  1. west (the Zephyr build tool) is discoverable + responsive — the direct
-//     analog of "arduino-cli is installed". discoverWest() already confirms
+//     toolchain presence. discoverWest() already confirms
 //     responsiveness via `west --version`; we additionally capture the version
 //     string to report it.
 //  2. the configured board target exists in the Zephyr checkout
@@ -117,7 +117,7 @@ export function boardExistsInCheckout(boardId, zephyrBase) {
  * checkout. Reports what (if anything) is wrong.
  *
  * - If `buildTarget` is undefined/empty, the board check is skipped (not a
- *   failure), mirroring Arduino's no-FQBN path.
+ *   failure), mirroring the no-build-target path.
  * - Never installs anything. Never mutates the user environment.
  * - Never throws — always returns a result. Callers decide how to react.
  *
@@ -165,7 +165,7 @@ export function checkZephyrEnv(buildTarget, options) {
             check,
             messages: [
                 `Zephyr ${zephyrVersion} is outside the supported range (${compat.range}) for @typecad/framework-zephyr.`,
-                "  Set ZEPHYR_BASE to a compatible Zephyr checkout, or install one via '@typecad/zephyr-installer'.",
+                "  Set ZEPHYR_BASE to a compatible Zephyr checkout, or or run the bundled Zephyr installer (npx --package @typecad/framework-zephyr zephyr-installer).",
             ],
             fixCommand: undefined,
         };

package/dist/toolchain/index.d.ts

@@ -1,4 +1,32 @@
 import type { ToolchainOptions, CompileResult, UploadResult } from '@typecad/cuttlefish/api/shared';
+import type { ZephyrChipDescriptor } from '../chips/types.js';
+/**
+ * Distinct DT-bound sensors the emitted sources reference — the lowering's
+ * state blocks name each one `__tc_sensor_<part>_i2c<N>_0x<addr>_dev`
+ * (lowering/sensor.ts sensorNames), so var-presence is the authoritative
+ * signal. Feeds the overlay's DT child nodes; the part group is greedy so a
+ * compatible containing '_i2c<N>_' still resolves to the longest part match.
+ */
+export interface ScannedSensorPart {
+    part: string;
+    busIndex: number;
+    port: number;
+    busKind: 'i2c' | 'spi';
+    spiHz: number;
+    spiMode: number;
+    alertPin: number;
+}
+export interface ScannedSpiTarget {
+    busIndex: number;
+    cs: number;
+    hz: number;
+    mode: number;
+}
+/** Scan the emitted source for thin SPI targets (hal/spi-target.ts): the
+ *  spi_dt_spec state block's tc-spit-cfg comment carries the construction
+ *  facts, the same channel tc-sensor-cfg uses. */
+export declare function scanSpiTargets(src: string): ScannedSpiTarget[];
+export declare function scanSensorParts(src: string): ScannedSensorPart[];
 /**
  * Derive the Zephyr project root from the cuttlefish-emitted source path.
  *
@@ -26,7 +54,44 @@ export declare function projectRootFromOptions(o: ToolchainOptions): string;
  * 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[];
+/**
+ * Resolve HOW this build attaches to the board for flashing OR debugging:
+ * the friendly `zephyr.probe` id from the board's probeMethods table (quirks
+ * included), or the raw `zephyr.runner` escape hatch. Exported (pure) so the
+ * selection contract is unit-testable without spawning west.
+ *
+ * Rules:
+ * - `probe` + `runner` together is an error (two ways of saying it — pick one).
+ * - An unknown `probe` id is an error listing what the board supports; a board
+ *   with no probeMethods table gets a hint to use `runner` directly.
+ * - purpose 'debug': the chosen method must be debug-capable (`debug` is not
+ *   false — a bootloader is not a debugger). Non-capable or unknown ids list
+ *   the debug-capable methods.
+ * - User `runnerArgs` are appended AFTER the method's args, so they can
+ *   override the method's baked-in flags (argparse takes the last value).
+ */
+export type ProbeResolution = {
+    ok: true;
+    runner?: string;
+    args: string[];
+} | {
+    ok: false;
+    error: string;
+};
+export declare function resolveProbeMethod(zc: Record<string, unknown> | undefined, chip: ZephyrChipDescriptor, purpose?: 'flash' | 'debug'): ProbeResolution;
+/**
+ * Whether a flash runner carries the upload over a serial port. Runner-gated,
+ * never board-name-gated: esptool and bossac are the only runners
+ * `buildFlashArgs` forwards `--port` to, so they are the only ones that
+ * cannot flash without one. Probe runners (openocd, jlink) and USB flows
+ * (dfu-util, uf2 mass storage) need no port — a missing `--port` must not
+ * block them.
+ *
+ * Exported (pure) so the port-requirement contract is unit-testable without
+ * spawning west.
+ */
+export declare function uploadRequiresPort(runner: string | undefined): boolean;
+export declare function buildFlashArgs(buildDir: string, userRunner: string | undefined, port: string | undefined, flashRunner?: string, runnerArgs?: readonly string[]): string[];
 /**
  * Classify a `west flash` result as success/failure.
  *