@typecad/framework-zephyr 1.0.0-alpha.10

package/src/toolchain/compat.ts

@@ -0,0 +1,145 @@
+// Zephyr version compatibility + board-target normalization.
+//
+// Two mechanisms absorb Zephyr version churn:
+//  1. checkZephyrCompat() — compare the installed Zephyr version against the
+//     declared range (manifest.compat.zephyr) so an incompatible Zephyr fails
+//     fast with a clear message instead of a cryptic west/CMake board error.
+//  2. resolveBoardTarget() — normalize the board target for the installed
+//     Zephyr version. Zephyr 4.3+ rejects bare multi-core board names
+//     (esp32s3_devkitc) and requires a qualified target
+//     (esp32s3_devkitc/esp32s3/procpu). This rewrites stale configs at build
+//     time so users don't have to regenerate them after a Zephyr upgrade.
+//
+// This module is intentionally pure (no chalk/ui/console) so it unit-tests
+// cleanly; the doctor and the toolchain decide how to present results.
+
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import manifest from '../framework.manifest.js';
+
+// ── minimal semver ──────────────────────────────────────────────────────────
+
+/** Parse "4.3.99" / "v4.3" / "4.3.99-rc1" → [4, 3, 99]. Undefined if unparseable. */
+export function parseVersion(v: string | undefined): [number, number, number] | undefined {
+  if (!v) return undefined;
+  const m = v.replace(/^v/i, '').match(/^(\d+)(?:\.(\d+))?(?:\.(\d+))?/);
+  if (!m) return undefined;
+  return [Number(m[1]), Number(m[2] ?? 0), Number(m[3] ?? 0)];
+}
+
+/** Compare two version strings: -1 if a<b, 0 if equal, 1 if a>b. */
+export function compareVersion(a: string, b: string): number {
+  const pa = parseVersion(a) ?? [0, 0, 0];
+  const pb = parseVersion(b) ?? [0, 0, 0];
+  for (let i = 0; i < 3; i++) {
+    if (pa[i]! < pb[i]!) return -1;
+    if (pa[i]! > pb[i]!) return 1;
+  }
+  return 0;
+}
+
+/**
+ * Evaluate a simple range of space-separated comparators against a version.
+ * Supported operators: >= <= > < =. Each comparator glues the operator to its
+ * version (">=4.3", "<5.0"); spaces between comparators are AND.
+ *   satisfiesRange("4.3.99", ">=4.3 <5.0") === true
+ */
+export function satisfiesRange(version: string, range: string): boolean {
+  return range
+    .trim()
+    .split(/\s+/)
+    .every((clause) => {
+      const m = clause.replace(/\s+/g, '').match(/^(>=|<=|>|<|=)(.+)$/);
+      if (!m) return true; // ignore anything that isn't a comparator
+      const cmp = compareVersion(version, m[2]!);
+      switch (m[1]) {
+        case '>=': return cmp >= 0;
+        case '<=': return cmp <= 0;
+        case '>': return cmp > 0;
+        case '<': return cmp < 0;
+        case '=': return cmp === 0;
+        default: return true;
+      }
+    });
+}
+
+// ── Zephyr version detection ────────────────────────────────────────────────
+
+/**
+ * Detect the installed Zephyr version from ZEPHYR_BASE/VERSION. Returns
+ * undefined when ZEPHYR_BASE is unset or VERSION can't be read/parsed. Handles
+ * the CMake-style file (VERSION_MAJOR = 4 / VERSION_MINOR = 3 / PATCHLEVEL = 99)
+ * and a bare "4.3.99".
+ */
+export function detectZephyrVersion(): string | undefined {
+  const base = process.env.ZEPHYR_BASE;
+  if (!base) return undefined;
+  let content: string;
+  try {
+    content = readFileSync(join(base, 'VERSION'), 'utf-8');
+  } catch {
+    return undefined;
+  }
+  const field = (key: string): string | undefined => {
+    const m = content.match(new RegExp(`^\\s*${key}\\s*=\\s*(\\d+)`, 'm'));
+    return m ? m[1] : undefined;
+  };
+  const major = field('VERSION_MAJOR');
+  if (major !== undefined) {
+    return `${major}.${field('VERSION_MINOR') ?? 0}.${field('PATCHLEVEL') ?? 0}`;
+  }
+  const m = content.match(/(\d+\.\d+(?:\.\d+)?)/);
+  return m ? m[1] : undefined;
+}
+
+// ── compat check ────────────────────────────────────────────────────────────
+
+export type CompatStatus = 'ok' | 'undetectable' | 'out-of-range';
+
+export interface CompatResult {
+  version: string | undefined;
+  /** Declared supported range (manifest.compat.zephyr), if any. */
+  range: string | undefined;
+  status: CompatStatus;
+}
+
+/**
+ * Compare the detected Zephyr version against the declared compat range. Pure:
+ * returns a status; the caller decides whether to throw/warn. 'ok' covers both
+ * "in range" and "no range declared".
+ */
+export function checkZephyrCompat(version: string | undefined): CompatResult {
+  const range = manifest.compat?.zephyr;
+  if (!range) return { version, range, status: 'ok' };
+  if (version === undefined) return { version, range, status: 'undetectable' };
+  return { version, range, status: satisfiesRange(version, range) ? 'ok' : 'out-of-range' };
+}
+
+// ── board-target normalization ──────────────────────────────────────────────
+
+/**
+ * For Zephyr >=4.3, multi-core ESP32 boards require a qualified board target
+ * (board/<soc>/<core>) — the bare id is rejected with "Board qualifiers … not
+ * found". Map each known multi-core board id to its procpu (main app core)
+ * qualified form. procpu is the core that runs application firmware; appcpu is
+ * the secondary core (selected explicitly only when offloading to it).
+ */
+const QUALIFIED_TARGETS_GE_4_3: Record<string, string> = {
+  esp32_devkitc: 'esp32_devkitc/esp32/procpu',
+  esp32s3_devkitc: 'esp32s3_devkitc/esp32s3/procpu',
+};
+
+/**
+ * Normalize a board target for the installed Zephyr version. Rewrites a stale
+ * bare id (esp32s3_devkitc) to the qualified form on Zephyr >=4.3; idempotent
+ * if the target is already qualified. Older Zephyr, single-core boards
+ * (xiao_ble), and unknown boards pass through unchanged.
+ */
+export function resolveBoardTarget(boardTarget: string, version: string | undefined): string {
+  const boardId = boardTarget.split('/')[0]!;
+  if (version !== undefined && satisfiesRange(version, '>=4.3')) {
+    const qualified = QUALIFIED_TARGETS_GE_4_3[boardId];
+    if (qualified) return qualified;
+  }
+  return boardTarget;
+}

package/src/toolchain/debug-config.ts

@@ -0,0 +1,399 @@
+// ---------------------------------------------------------------------------
+// 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';
+
+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 function resolveGdbPath(buildDir: string, target: string): string | undefined {
+  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(): string | undefined {
+  const candidates: string[] = [];
+  // 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: string[] = [];
+    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: string): {
+  workspaceRoot: string;
+  sketchRel: string;
+} {
+  // 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<T extends Record<string, unknown>>(
+  filePath: string,
+  arrayKey: string,
+  matchKey: string,
+  entry: T,
+): void {
+  let doc: Record<string, unknown> = {};
+  if (existsSync(filePath)) {
+    try {
+      doc = JSON.parse(readFileSync(filePath, 'utf-8'));
+    } catch {
+      // malformed — start fresh
+    }
+  }
+  const arr = Array.isArray(doc[arrayKey]) ? (doc[arrayKey] as T[]) : [];
+  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?: string): string | null {
+  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: DebugConfigOptions,
+  gdbScriptRel: string | undefined,
+  openOcdCfgRel: string,
+): Record<string, unknown> {
+  // 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: Record<string, unknown> = {
+    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: DebugConfigOptions): Record<string, unknown> {
+  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(): string {
+  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: DebugConfigOptions): void {
+  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: string | undefined;
+  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);
+}