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

package/dist/toolchain/debug-config.js

@@ -333,14 +333,24 @@ function buildLaunchConfig(o, gdbScriptRel, openOcdCfgRel, method) {
     // 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, '/');
+    // Paths in GDB commands must be RELATIVE (resolved against GDB's own
+    // working directory), never ${workspaceFolder} literals or absolute paths:
+    //   - cortex-debug passes command strings through verbatim — no variable
+    //     expansion in postAttachCommands (verified against its gdb.ts) — so a
+    //     ${workspaceFolder} would reach GDB as a literal.
+    //   - Even where VS Code expands it, on Windows the expansion carries
+    //     backslashes that GDB reads as escape sequences (\t → tab, etc.).
+    //   - An absolute path bakes the generating machine's checkout location
+    //     into launch.json and breaks on every other clone/checkout.
+    // cortex-debug spawns GDB with cwd from the config's `cwd` field
+    // (${workspaceFolder} above), so a relative path IS the workspace root —
+    // `set directories .` adds exactly the directory the old absolute form did,
+    // and `source <rel>` finds the frame-filter script.
     // 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 directories .',
         'set remote hardware-watchpoint-limit 2',
         'set remote hardware-breakpoint-limit 2',
         ...(isEsp32Target ? [
@@ -352,7 +362,7 @@ function buildLaunchConfig(o, gdbScriptRel, openOcdCfgRel, method) {
         ...(isEsp32Target ? ['c'] : []),
     ];
     if (gdbScriptRel) {
-        postAttachCommands.splice(1, 0, `source ${ws}/${gdbScriptRel}`);
+        postAttachCommands.splice(1, 0, `source ${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

package/dist/toolchain/index.d.ts

@@ -79,6 +79,45 @@ export type ProbeResolution = {
     error: string;
 };
 export declare function resolveProbeMethod(zc: Record<string, unknown> | undefined, chip: ZephyrChipDescriptor, purpose?: 'flash' | 'debug'): ProbeResolution;
+/**
+ * Run an openocd session against the board's probe config — the shared
+ * engine for the pre-flash quiesce and the post-flash SYSRESETREQ (see the
+ * call sites in upload()). The config is the probe method's verbatim
+ * debugCfg from the board catalog (the same lines `west debug` uses);
+ * `commands` are appended after `-f <cfg> -c init`. Returns a flash note on
+ * success, undefined when skipped or failed (best-effort by design).
+ */
+/**
+ * Resolve the openocd binary (plus script search dirs) for the probe session.
+ *
+ * Resolution order mirrors how west's own openocd runner finds the binary, so
+ * the session and `west flash` drive the SAME openocd:
+ *   1. $OPENOCD — the variable Zephyr's CMake reads into the build cache.
+ *   2. A Zephyr-SDK-hosted install ($ZEPHYR_SDK_INSTALL_DIR, else the
+ *      discovered west install's SDK). Layout differs by SDK generation —
+ *      hosttools/openocd/share/openocd/scripts vs hosttools/openocd/scripts —
+ *      so both script dirs are collected.
+ *   3. PATH — Linux distro / conda / micromamba installs (a micromamba-env
+ *      openocd is the common Linux setup; the SDK layout check alone made the
+ *      deterministic probe session unreachable there, silently dropping every
+ *      Linux flash to the racy `west flash` fallback).
+ *
+ * A non-SDK binary resolves with no explicit -s dirs: it finds its own
+ * interface/target scripts via its compiled-in search path. Returns undefined
+ * when no openocd can be found (the caller then uses the west fallback).
+ *
+ * Exported (pure) so the resolution contract is unit-testable without
+ * spawning openocd.
+ */
+export interface SessionOpenOcd {
+    readonly exe: string;
+    readonly searchDirs: readonly string[];
+}
+export declare function resolveSessionOpenOcd(env?: {
+    OPENOCD?: string | undefined;
+    ZEPHYR_SDK_INSTALL_DIR?: string | undefined;
+    PATH?: string | undefined;
+}, sdkInstallDir?: string): SessionOpenOcd | undefined;
 /**
  * Whether a flash runner carries the upload over a serial port. Runner-gated,
  * never board-name-gated: esptool and bossac are the only runners
@@ -111,6 +150,16 @@ export declare function buildFlashArgs(buildDir: string, userRunner: string | un
  * Exported (pure) so the classification is unit-testable without spawning west.
  */
 export declare function classifyUploadResult(runner: string | undefined, status: number | null, output: string): boolean;
+/**
+ * Whether a `west flash` (openocd) output carries one of the known
+ * target-ignored-SWD signatures — the DAP connect failing ("init mode
+ * failed (unable to connect to the target)", i.e. the DPIDR read never
+ * succeeded) or a reset/halt never landing ("timed out while waiting for
+ * target halted" / "TARGET: <name> - Not halted"). Both mean the board (or
+ * probe) needs a power-cycle or the SWD-free DFU path, not a retry of the
+ * same command. Centralized so the upload hint stays testable.
+ */
+export declare function isTargetSwdFailure(output: string): boolean;
 /**
  * Cleanse the `west flash` output shown to the user.
  *

package/dist/toolchain/index.js

@@ -18,7 +18,7 @@
 // target is known), GCC errors parsed via the shared parseCompileErrors helper.
 // ---------------------------------------------------------------------------
 import { spawnSync } from 'node:child_process';
-import { basename, dirname, join } from 'node:path';
+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';
@@ -322,14 +322,31 @@ export function resolveProbeMethod(zc, chip, purpose = 'flash') {
     }
     return { ok: true, runner, args: userArgs };
 }
-/**
- * Run an openocd session against the board's probe config — the shared
- * engine for the pre-flash quiesce and the post-flash SYSRESETREQ (see the
- * call sites in upload()). The config is the probe method's verbatim
- * debugCfg from the board catalog (the same lines `west debug` uses);
- * `commands` are appended after `-f <cfg> -c init`. Returns a flash note on
- * success, undefined when skipped or failed (best-effort by design).
- */
+export function resolveSessionOpenOcd(env = process.env, sdkInstallDir) {
+    const exeName = process.platform === 'win32' ? 'openocd.exe' : 'openocd';
+    if (env.OPENOCD && existsSync(env.OPENOCD)) {
+        return { exe: env.OPENOCD, searchDirs: [] };
+    }
+    const sdkRoot = env.ZEPHYR_SDK_INSTALL_DIR || sdkInstallDir;
+    if (sdkRoot) {
+        const exe = join(sdkRoot, 'hosttools', 'openocd', 'bin', exeName);
+        if (existsSync(exe)) {
+            const searchDirs = [
+                join(sdkRoot, 'hosttools', 'openocd', 'share', 'openocd', 'scripts'),
+                join(sdkRoot, 'hosttools', 'openocd', 'scripts'),
+            ].filter((d) => existsSync(d));
+            return { exe, searchDirs };
+        }
+    }
+    for (const dir of (env.PATH ?? '').split(delimiter)) {
+        if (!dir)
+            continue;
+        const candidate = join(dir, exeName);
+        if (existsSync(candidate))
+            return { exe: candidate, searchDirs: [] };
+    }
+    return undefined;
+}
 function openocdProbeSession(buildDir, zc, chip, commands) {
     // Config resolution — two sources, in order:
     //   1. The named probe method's verbatim debugCfg from the board catalog
@@ -360,17 +377,11 @@ function openocdProbeSession(buildDir, zc, chip, commands) {
             .map((a) => a.slice('--cmd-pre-init='.length)),
     ];
     const install = discoverWest();
-    const sdkRoot = process.env.ZEPHYR_SDK_INSTALL_DIR || install?.sdkInstallDir;
-    if (!sdkRoot)
-        return undefined;
-    const openocdExe = join(sdkRoot, 'hosttools', 'openocd', 'bin', process.platform === 'win32' ? 'openocd.exe' : 'openocd');
-    if (!existsSync(openocdExe))
+    const sessionOpenOcd = resolveSessionOpenOcd(process.env, install?.sdkInstallDir);
+    if (!sessionOpenOcd)
         return undefined;
-    // Script search path: the SDK layouts differ across versions — prefer the
-    // share/ form west's own runner uses, fall back to the scripts/ form.
-    const shareScripts = join(sdkRoot, 'hosttools', 'openocd', 'share', 'openocd', 'scripts');
-    const binScripts = join(sdkRoot, 'hosttools', 'openocd', 'scripts');
-    const searchDir = existsSync(shareScripts) ? shareScripts : binScripts;
+    const openocdExe = sessionOpenOcd.exe;
+    const searchArgs = sessionOpenOcd.searchDirs.flatMap((d) => ['-s', d]);
     let cfgArgs;
     let sessionCfg;
     if (cfgLines && cfgLines.length > 0) {
@@ -409,7 +420,7 @@ function openocdProbeSession(buildDir, zc, chip, commands) {
             cfgArgs = ['-f', sessionCfg];
         }
         const res = spawnSync(openocdExe, [
-            '-s', searchDir, ...cfgArgs,
+            ...searchArgs, ...cfgArgs,
             // Pre-init TCL AFTER the cfg (overrides its reset_config) and BEFORE
             // init — the same position west gives --cmd-pre-init.
             ...preInit.map((c) => ['-c', c]).flat(),
@@ -503,6 +514,18 @@ function isUf2DriveVanishRace(output) {
         && /WinError 433/.test(output)
         && /copymode/.test(output);
 }
+/**
+ * Whether a `west flash` (openocd) output carries one of the known
+ * target-ignored-SWD signatures — the DAP connect failing ("init mode
+ * failed (unable to connect to the target)", i.e. the DPIDR read never
+ * succeeded) or a reset/halt never landing ("timed out while waiting for
+ * target halted" / "TARGET: <name> - Not halted"). Both mean the board (or
+ * probe) needs a power-cycle or the SWD-free DFU path, not a retry of the
+ * same command. Centralized so the upload hint stays testable.
+ */
+export function isTargetSwdFailure(output) {
+    return /unable to connect to the target|timed out while waiting for target halted|TARGET: \S+ - Not halted/.test(output);
+}
 /**
  * Cleanse the `west flash` output shown to the user.
  *
@@ -1112,6 +1135,12 @@ export const Toolchain = {
                 ]);
                 if (revived)
                     flashNotes.push(revived);
+                // Known SWD-failure signatures get a recovery pointer — a board that
+                // ignores SWD until power-cycled (low-power state, lockup, a wedged
+                // probe) otherwise reads as a toolchain bug.
+                if (isTargetSwdFailure(raw)) {
+                    flashNotes.push('-- target ignored SWD — if a retry fails too: power-cycle the board, replug the probe, or skip SWD entirely (hold BOOT0, tap reset, re-run with --probe dfu)');
+                }
             }
         }
         else {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@typecad/framework-zephyr",
-  "version": "1.0.0-alpha.15",
+  "version": "1.0.0-alpha.16",
   "description": "TypeCAD framework package for the Zephyr RTOS \u2014 west/CMake build, devicetree-driven GPIO",
   "type": "module",
   "main": "./dist/index.js",
@@ -38,11 +38,11 @@
     "dry-run": "node installer/install.mjs --dry-run"
   },
   "dependencies": {
-    "@typecad/cuttlefish": "1.0.0-alpha.15",
-    "@typecad/hal": "1.0.0-alpha.15"
+    "@typecad/cuttlefish": "1.0.0-alpha.16",
+    "@typecad/hal": "1.0.0-alpha.16"
   },
   "devDependencies": {
-    "@typecad/expect": "1.0.0-alpha.15",
+    "@typecad/expect": "1.0.0-alpha.16",
     "typescript": "^5.7.3"
   },
   "license": "MIT",

package/src/toolchain/debug-config.ts

@@ -369,14 +369,24 @@ function buildLaunchConfig(
   // 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, '/');
+  // Paths in GDB commands must be RELATIVE (resolved against GDB's own
+  // working directory), never ${workspaceFolder} literals or absolute paths:
+  //   - cortex-debug passes command strings through verbatim — no variable
+  //     expansion in postAttachCommands (verified against its gdb.ts) — so a
+  //     ${workspaceFolder} would reach GDB as a literal.
+  //   - Even where VS Code expands it, on Windows the expansion carries
+  //     backslashes that GDB reads as escape sequences (\t → tab, etc.).
+  //   - An absolute path bakes the generating machine's checkout location
+  //     into launch.json and breaks on every other clone/checkout.
+  // cortex-debug spawns GDB with cwd from the config's `cwd` field
+  // (${workspaceFolder} above), so a relative path IS the workspace root —
+  // `set directories .` adds exactly the directory the old absolute form did,
+  // and `source <rel>` finds the frame-filter script.
   // 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 directories .',
     'set remote hardware-watchpoint-limit 2',
     'set remote hardware-breakpoint-limit 2',
     ...(isEsp32Target ? [
@@ -388,7 +398,7 @@ function buildLaunchConfig(
     ...(isEsp32Target ? ['c'] : []),
   ];
   if (gdbScriptRel) {
-    postAttachCommands.splice(1, 0, `source ${ws}/${gdbScriptRel}`);
+    postAttachCommands.splice(1, 0, `source ${gdbScriptRel}`);
   }
 
   // Probe-method-driven server shape: jlink-runner methods use cortex-debug's

package/src/toolchain/index.ts

@@ -19,7 +19,7 @@
 // ---------------------------------------------------------------------------
 
 import { spawnSync } from 'node:child_process';
-import { basename, dirname, join } from 'node:path';
+import { basename, delimiter, dirname, join } from 'node:path';
 import { readdirSync, readFileSync, mkdirSync, rmSync, existsSync, writeFileSync } from 'node:fs';
 import type { ToolchainOptions, CompileResult, UploadResult } from '@typecad/cuttlefish/api/shared';
 import { parseCompileErrors } from '@typecad/cuttlefish/api/shared';
@@ -402,6 +402,64 @@ export function resolveProbeMethod(
  * `commands` are appended after `-f <cfg> -c init`. Returns a flash note on
  * success, undefined when skipped or failed (best-effort by design).
  */
+/**
+ * Resolve the openocd binary (plus script search dirs) for the probe session.
+ *
+ * Resolution order mirrors how west's own openocd runner finds the binary, so
+ * the session and `west flash` drive the SAME openocd:
+ *   1. $OPENOCD — the variable Zephyr's CMake reads into the build cache.
+ *   2. A Zephyr-SDK-hosted install ($ZEPHYR_SDK_INSTALL_DIR, else the
+ *      discovered west install's SDK). Layout differs by SDK generation —
+ *      hosttools/openocd/share/openocd/scripts vs hosttools/openocd/scripts —
+ *      so both script dirs are collected.
+ *   3. PATH — Linux distro / conda / micromamba installs (a micromamba-env
+ *      openocd is the common Linux setup; the SDK layout check alone made the
+ *      deterministic probe session unreachable there, silently dropping every
+ *      Linux flash to the racy `west flash` fallback).
+ *
+ * A non-SDK binary resolves with no explicit -s dirs: it finds its own
+ * interface/target scripts via its compiled-in search path. Returns undefined
+ * when no openocd can be found (the caller then uses the west fallback).
+ *
+ * Exported (pure) so the resolution contract is unit-testable without
+ * spawning openocd.
+ */
+export interface SessionOpenOcd {
+  readonly exe: string;
+  readonly searchDirs: readonly string[];
+}
+
+export function resolveSessionOpenOcd(
+  env: {
+    OPENOCD?: string | undefined;
+    ZEPHYR_SDK_INSTALL_DIR?: string | undefined;
+    PATH?: string | undefined;
+  } = process.env,
+  sdkInstallDir?: string,
+): SessionOpenOcd | undefined {
+  const exeName = process.platform === 'win32' ? 'openocd.exe' : 'openocd';
+  if (env.OPENOCD && existsSync(env.OPENOCD)) {
+    return { exe: env.OPENOCD, searchDirs: [] };
+  }
+  const sdkRoot = env.ZEPHYR_SDK_INSTALL_DIR || sdkInstallDir;
+  if (sdkRoot) {
+    const exe = join(sdkRoot, 'hosttools', 'openocd', 'bin', exeName);
+    if (existsSync(exe)) {
+      const searchDirs = [
+        join(sdkRoot, 'hosttools', 'openocd', 'share', 'openocd', 'scripts'),
+        join(sdkRoot, 'hosttools', 'openocd', 'scripts'),
+      ].filter((d) => existsSync(d));
+      return { exe, searchDirs };
+    }
+  }
+  for (const dir of (env.PATH ?? '').split(delimiter)) {
+    if (!dir) continue;
+    const candidate = join(dir, exeName);
+    if (existsSync(candidate)) return { exe: candidate, searchDirs: [] };
+  }
+  return undefined;
+}
+
 function openocdProbeSession(
   buildDir: string,
   zc: Record<string, unknown> | undefined,
@@ -438,16 +496,10 @@ function openocdProbeSession(
   ];
 
   const install = discoverWest();
-  const sdkRoot = process.env.ZEPHYR_SDK_INSTALL_DIR || install?.sdkInstallDir;
-  if (!sdkRoot) return undefined;
-  const openocdExe = join(sdkRoot, 'hosttools', 'openocd', 'bin',
-    process.platform === 'win32' ? 'openocd.exe' : 'openocd');
-  if (!existsSync(openocdExe)) return undefined;
-  // Script search path: the SDK layouts differ across versions — prefer the
-  // share/ form west's own runner uses, fall back to the scripts/ form.
-  const shareScripts = join(sdkRoot, 'hosttools', 'openocd', 'share', 'openocd', 'scripts');
-  const binScripts = join(sdkRoot, 'hosttools', 'openocd', 'scripts');
-  const searchDir = existsSync(shareScripts) ? shareScripts : binScripts;
+  const sessionOpenOcd = resolveSessionOpenOcd(process.env, install?.sdkInstallDir);
+  if (!sessionOpenOcd) return undefined;
+  const openocdExe = sessionOpenOcd.exe;
+  const searchArgs = sessionOpenOcd.searchDirs.flatMap((d) => ['-s', d] as [string, string]);
 
   let cfgArgs: string[] | undefined;
   let sessionCfg: string | undefined;
@@ -481,7 +533,7 @@ function openocdProbeSession(
       cfgArgs = ['-f', sessionCfg];
     }
     const res = spawnSync(openocdExe, [
-      '-s', searchDir, ...cfgArgs!,
+      ...searchArgs, ...cfgArgs!,
       // Pre-init TCL AFTER the cfg (overrides its reset_config) and BEFORE
       // init — the same position west gives --cmd-pre-init.
       ...preInit.map((c) => ['-c', c] as [string, string]).flat(),
@@ -587,6 +639,19 @@ function isUf2DriveVanishRace(output: string): boolean {
     && /copymode/.test(output);
 }
 
+/**
+ * Whether a `west flash` (openocd) output carries one of the known
+ * target-ignored-SWD signatures — the DAP connect failing ("init mode
+ * failed (unable to connect to the target)", i.e. the DPIDR read never
+ * succeeded) or a reset/halt never landing ("timed out while waiting for
+ * target halted" / "TARGET: <name> - Not halted"). Both mean the board (or
+ * probe) needs a power-cycle or the SWD-free DFU path, not a retry of the
+ * same command. Centralized so the upload hint stays testable.
+ */
+export function isTargetSwdFailure(output: string): boolean {
+  return /unable to connect to the target|timed out while waiting for target halted|TARGET: \S+ - Not halted/.test(output);
+}
+
 /**
  * Cleanse the `west flash` output shown to the user.
  *
@@ -1216,6 +1281,14 @@ export const Toolchain = {
           'sleep 300',
         ]);
         if (revived) flashNotes.push(revived);
+        // Known SWD-failure signatures get a recovery pointer — a board that
+        // ignores SWD until power-cycled (low-power state, lockup, a wedged
+        // probe) otherwise reads as a toolchain bug.
+        if (isTargetSwdFailure(raw)) {
+          flashNotes.push(
+            '-- target ignored SWD — if a retry fails too: power-cycle the board, replug the probe, or skip SWD entirely (hold BOOT0, tap reset, re-run with --probe dfu)',
+          );
+        }
       }
     } else {
       ok = true;