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

package/installer/install.sh

@@ -0,0 +1,310 @@
+#!/usr/bin/env bash
+# ---------------------------------------------------------------------------
+# typeCAD Zephyr installer — POSIX bootstrap (Linux, macOS, Git Bash on Windows).
+#
+# One-command install of a working Zephyr build environment via micromamba:
+#   1. download the micromamba static binary (no preinstalled conda/Python needed)
+#   2. create a conda env with the host build tools (west, cmake, ninja, dtc, ...)
+#   3. install activation hooks that set ZEPHYR_BASE + ZEPHYR_SDK_INSTALL_DIR
+#   4. fetch + extract the official Zephyr SDK full bundle (cross-toolchains)
+#   5. west init + west update a vanilla Zephyr workspace
+#
+# After install: `micromamba activate zephyr` and framework-zephyr's west
+# discovery cascade (packages/framework-zephyr/src/toolchain/west-discover.ts)
+# picks up west via PATH + ZEPHYR_BASE automatically — no manual env vars.
+#
+# Usage:
+#   bash install.sh [--dry-run] [--no-sdk] [--no-workspace]
+#                   [--env-name NAME] [--sdk-version VER] [--help]
+#
+# --dry-run       print the resolved plan (URLs, paths, versions) and exit;
+#                 downloads/creates nothing. Used by the test suite.
+# --no-sdk        skip the Zephyr SDK download (env + workspace only).
+# --no-workspace  skip west init/update (env + SDK only).
+# --env-name      override the conda env name (default: zephyr).
+# --sdk-version   override the Zephyr SDK version (default: pinned in versions.env).
+# ---------------------------------------------------------------------------
+set -eu
+
+PKG_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# --- flag parsing -----------------------------------------------------------
+DRY_RUN=0
+DO_SDK=1
+DO_WORKSPACE=1
+ENV_NAME_OVERRIDE=""
+SDK_VERSION_OVERRIDE=""
+PLATFORMS=""
+
+usage() {
+  cat <<'EOF'
+Usage: bash install.sh [options]
+
+  --dry-run        Print the resolved plan (URLs, paths, versions) and exit.
+                   Downloads/creates nothing.
+  --no-sdk         Skip the Zephyr SDK download (env + workspace only).
+  --no-workspace   Skip west init/update (env + SDK only).
+  --modify         SDK platforms only: re-run selection and ADD the selected
+                   platforms with missing toolchains. Implies --no-workspace.
+  --prune          With --modify: also DELETE toolchains of platforms not in
+                   the selection (reclaim disk space). Without it, --modify
+                   is purely additive.
+  --platforms SEL  Comma-separated platform groups (arm,esp32,riscv,arc,rx,x86,aarch64)
+                   or 'all' for the full bundle. Default: all — RECOMMENDED:
+                   every board in the data pack builds as-is.
+  --env-name NAME  Override the conda env name (default: zephyr).
+  --sdk-version V  Override the Zephyr SDK version (default: pinned in versions.env).
+  -h, --help       Show this help.
+
+Environment overrides:
+  MAMBA_ROOT_PREFIX  micromamba root (default: ~/micromamba)
+  WORKSPACE_DIR      west workspace (default: ~/zephyrproject)
+  SDK_INSTALL_PARENT where the SDK extracts (default: inside the conda env)
+EOF
+}
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --dry-run)        DRY_RUN=1 ;;
+    --no-sdk)         DO_SDK=0 ;;
+    --no-workspace)   DO_WORKSPACE=0 ;;
+    --modify|-m)      DO_WORKSPACE=0 ;;
+    --prune)          PRUNE=1 ;;
+    --platforms)      PLATFORMS="${2:?--platforms needs a value}"; shift ;;
+    --env-name)       ENV_NAME_OVERRIDE="${2:?--env-name needs a value}"; shift ;;
+    --sdk-version)    SDK_VERSION_OVERRIDE="${2:?--sdk-version needs a value}"; shift ;;
+    -h|--help)        usage; exit 0 ;;
+    *) echo "install: unknown flag: $1" >&2; usage >&2; exit 2 ;;
+  esac
+  shift
+done
+
+: "${PLATFORMS:=all}"
+export PRUNE="${PRUNE:-0}"
+
+# --- load pinned versions + library functions -------------------------------
+# shellcheck source=versions.env
+. "$PKG_DIR/versions.env"
+# shellcheck source=lib/detect-platform.sh
+. "$PKG_DIR/lib/detect-platform.sh"
+# shellcheck source=lib/fetch-sdk.sh
+. "$PKG_DIR/lib/fetch-sdk.sh"
+# shellcheck source=lib/init-workspace.sh
+. "$PKG_DIR/lib/init-workspace.sh"
+# shellcheck source=lib/write-activation.sh
+. "$PKG_DIR/lib/write-activation.sh"
+
+# Apply CLI overrides.
+[ -n "$ENV_NAME_OVERRIDE" ] && ENV_NAME="$ENV_NAME_OVERRIDE"
+[ -n "$SDK_VERSION_OVERRIDE" ] && ZEPHYR_SDK_VERSION="$SDK_VERSION_OVERRIDE"
+
+# --- platform detection -----------------------------------------------------
+detect_platform
+
+# --- path resolution --------------------------------------------------------
+: "${MAMBA_ROOT_PREFIX:=$HOME/micromamba}"
+: "${WORKSPACE_DIR:=$HOME/zephyrproject}"
+ENV_PREFIX="$MAMBA_ROOT_PREFIX/envs/$ENV_NAME"
+# SDK lives OUTSIDE the env prefix: `micromamba create` requires the prefix
+# empty, and a failed create must not trap a multi-GB SDK download.
+: "${SDK_INSTALL_PARENT:=$MAMBA_ROOT_PREFIX/zephyr-sdk}"
+ZEPHYR_SDK_INSTALL_DIR="$SDK_INSTALL_PARENT/zephyr-sdk-$ZEPHYR_SDK_VERSION"
+
+# micromamba binary lives at different paths on POSIX vs Windows (the win-64
+# tarball ships Library/bin/micromamba.exe, not bin/micromamba).
+case "$MAMBA_PLAT" in
+  win-*) : "${MAMBA:=$MAMBA_ROOT_PREFIX/Library/bin/micromamba.exe}" ;;
+  *)     : "${MAMBA:=$MAMBA_ROOT_PREFIX/bin/micromamba}" ;;
+esac
+
+# --- plan printer (greppable: every line tagged [plan]) ---------------------
+print_plan() {
+  local bundle="zephyr-sdk-${ZEPHYR_SDK_VERSION}_${SDK_PLAT}${ZEPHYR_SDK_BUNDLE_SUFFIX}.${ARCHIVE_EXT}"
+  echo "[plan] typeCAD Zephyr installer"
+  echo "[plan]   env name:          $ENV_NAME"
+  echo "[plan]   conda subdir:      $MAMBA_PLAT"
+  echo "[plan]   sdk platform:      $SDK_PLAT"
+  echo "[plan]   sdk version:       $ZEPHYR_SDK_VERSION"
+  echo "[plan]   platforms:         $PLATFORMS"
+  echo "[plan]   sdk bundle:        $bundle"
+  echo "[plan]   sdk bundle url:    $SDK_RELEASE_BASE/v$ZEPHYR_SDK_VERSION/$bundle"
+  echo "[plan]   micromamba url:    $MICROMAMBA_BASE/$MAMBA_PLAT/latest"
+  echo "[plan]   micromamba bin:    $MAMBA"
+  echo "[plan]   env prefix:        $ENV_PREFIX"
+  echo "[plan]   sdk install dir:   $ZEPHYR_SDK_INSTALL_DIR"
+  echo "[plan]   workspace dir:     $WORKSPACE_DIR"
+  echo "[plan]   zephyr base:       $WORKSPACE_DIR/zephyr"
+  echo "[plan]   manifest url:      $ZEPHYR_MANIFEST_URL"
+  echo "[plan]   manifest rev:      $ZEPHYR_MANIFEST_REV"
+  echo "[plan]   do sdk:            $DO_SDK"
+  echo "[plan]   do workspace:      $DO_WORKSPACE"
+}
+
+print_plan
+
+if [ "$DRY_RUN" = "1" ]; then
+  echo "[plan] DRY-RUN — no downloads, no env created."
+  exit 0
+fi
+
+# --- 1. micromamba ----------------------------------------------------------
+download_micromamba() {
+  if [ -x "$MAMBA" ]; then
+    echo "micromamba: already present at $MAMBA"
+    return 0
+  fi
+  echo "micromamba: downloading ($MAMBA_PLAT)..."
+  mkdir -p "$MAMBA_ROOT_PREFIX"
+  curl -Ls "$MICROMAMBA_BASE/$MAMBA_PLAT/latest" | tar -xvj -C "$MAMBA_ROOT_PREFIX"
+  if [ ! -x "$MAMBA" ]; then
+    # Windows tarballs may land at a different inner path; locate it as a fallback.
+    local found
+    found="$(find "$MAMBA_ROOT_PREFIX" -name 'micromamba*' -type f 2>/dev/null | head -1 || true)"
+    [ -n "$found" ] && MAMBA="$found"
+  fi
+  if [ ! -x "$MAMBA" ]; then
+    echo "micromamba: download failed — binary not found under $MAMBA_ROOT_PREFIX" >&2
+    return 1
+  fi
+  echo "micromamba: installed at $MAMBA"
+}
+
+download_micromamba
+export MAMBA_ROOT_PREFIX
+
+# Register the micromamba shell hook in ~/.bashrc so `micromamba` is on PATH
+# and `micromamba activate <env>` works in new bash shells. micromamba lands
+# under $MAMBA_ROOT_PREFIX/bin, which is not on PATH by default.
+echo "micromamba: registering shell hook in ~/.bashrc..."
+"$MAMBA" shell init -s bash -r "$MAMBA_ROOT_PREFIX" \
+  || echo "micromamba: shell init (bash) failed — non-fatal; run it manually" >&2
+
+# --- 2. conda env (host tools) ---------------------------------------------
+create_env() {
+  if [ -d "$ENV_PREFIX" ] && "$MAMBA" env list 2>/dev/null | grep -q "^${ENV_NAME} "; then
+    echo "env: '$ENV_NAME' already exists at $ENV_PREFIX — updating"
+    "$MAMBA" env update -y -f "$PKG_DIR/environment.yml" -p "$ENV_PREFIX" || {
+      echo "env: env update failed" >&2; return 1; }
+  elif [ -e "$ENV_PREFIX" ]; then
+    # Prefix dir exists but micromamba doesn't list it as an env (no conda-meta).
+    # `create` would abort with "Non-conda folder exists at prefix". Surface it
+    # rather than auto-deleting a dir that may hold a multi-GB SDK.
+    echo "env: ERROR — '$ENV_PREFIX' exists but is not a valid conda env (no conda-meta)." >&2
+    echo "env:   Usually left by a prior failed run. Remove it and re-run:" >&2
+    echo "env:     rm -rf '$ENV_PREFIX'" >&2
+    return 1
+  else
+    echo "env: creating '$ENV_NAME' from environment.yml..."
+    "$MAMBA" create -y -f "$PKG_DIR/environment.yml" -n "$ENV_NAME" || {
+      echo "env: env create failed" >&2; return 1; }
+  fi
+}
+
+# Platform-limited host tools that can't live in environment.yml (micromamba
+# ignores `# [not win]` selectors, so they'd break the solve on Windows).
+#   dtc     — conda-forge has it for all POSIX subdirs. Needed for devicetree.
+#   openocd — conda-forge has it ONLY for linux-64 / osx-64 (no arm64, no win).
+# Both are optional for the env to exist; we warn on failure so the env stays
+# usable rather than aborting the whole install over a flashing/debug helper.
+install_platform_tools() {
+  if [[ "$MAMBA_PLAT" == win-* ]]; then
+    echo "env: Windows host via install.sh — skipping POSIX-only tools."
+    echo "env:   (On Windows, use 'node install.mjs' / install.ps1, which installs 7zip instead.)"
+    return 0
+  fi
+  echo "env: installing POSIX host tools (dtc, openocd)..."
+  if ! "$MAMBA" install -y -n "$ENV_NAME" -c conda-forge dtc >/dev/null 2>&1; then
+    echo "env: WARNING — dtc not installed on $MAMBA_PLAT." >&2
+    echo "env:   Zephyr builds needing the C devicetree compiler will fail until dtc is available." >&2
+  fi
+  if ! "$MAMBA" install -y -n "$ENV_NAME" -c conda-forge openocd >/dev/null 2>&1; then
+    echo "env: note — openocd not available on $MAMBA_PLAT (only x86_64 POSIX); skipped." >&2
+    echo "env:   only needed for JTAG/SWD flashing; nRF boards use nrfjprog/pyocd." >&2
+  fi
+  # dfu-util — west flash's dfu-util runner (STM32 ROM DFU bootloader boards,
+  # e.g. the WeAct Black Pill) shells out to it; a missing executable makes
+  # the runner die with a raw FileNotFoundError. Not on conda-forge either, so
+  # fall back to the system package manager. No auto-sudo: warn with the
+  # right command instead of failing the install over a flashing helper.
+  if ! command -v dfu-util >/dev/null 2>&1; then
+    echo "env: dfu-util not found — west flash on DFU-bootloader boards (STM32) needs it." >&2
+    case "$(uname -s)" in
+      Linux)
+        if command -v apt-get >/dev/null 2>&1; then
+          echo "env:   install with: sudo apt-get install dfu-util" >&2
+        elif command -v dnf >/dev/null 2>&1; then
+          echo "env:   install with: sudo dnf install dfu-util" >&2
+        elif command -v pacman >/dev/null 2>&1; then
+          echo "env:   install with: sudo pacman -S dfu-util" >&2
+        else
+          echo "env:   install dfu-util via your distribution's package manager." >&2
+        fi ;;
+      Darwin)
+        echo "env:   install with: brew install dfu-util" >&2 ;;
+      *)
+        echo "env:   install dfu-util via your package manager (https://dfu-util.sourceforge.net)." >&2 ;;
+    esac
+  fi
+  # bossac — west flash's bossac runner (SAMD SAM-BA bootloader boards — the
+  # Arduino Nano 33 IoT, Zero, MKR series) shells out to it, and Zephyr's
+  # FindHostTools resolves find_program(BOSSAC) at build-configure time, so it
+  # must be on PATH BEFORE building. In neither the Zephyr SDK nor conda-forge;
+  # no auto-sudo — warn with the right command instead.
+  if ! command -v bossac >/dev/null 2>&1; then
+    echo "env: bossac not found — west flash on SAM-BA-bootloader boards (SAMD) needs it." >&2
+    case "$(uname -s)" in
+      Linux)
+        if command -v apt-get >/dev/null 2>&1; then
+          echo "env:   install with: sudo apt-get install bossa-cli" >&2
+        else
+          echo "env:   install bossac via your distribution's package manager, or build it: https://github.com/shumatech/BOSSA" >&2
+        fi ;;
+      Darwin)
+        echo "env:   install with: brew install bossa" >&2 ;;
+      *)
+        echo "env:   install bossac via your package manager (https://github.com/shumatech/BOSSA)." >&2 ;;
+    esac
+  fi
+}
+
+create_env
+install_platform_tools
+
+# --- 3. activation hooks ---------------------------------------------------
+write_activation
+
+# --- 4. Zephyr SDK ---------------------------------------------------------
+if [ "$DO_SDK" = "1" ]; then
+  fetch_sdk
+else
+  echo "install: --no-sdk — skipping Zephyr SDK download"
+fi
+
+# --- 5. west workspace -----------------------------------------------------
+if [ "$DO_WORKSPACE" = "1" ]; then
+  init_workspace
+else
+  echo "install: --no-workspace — skipping west init/update"
+fi
+
+# --- done -------------------------------------------------------------------
+cat <<EOF
+
+install: done.
+
+The micromamba shell hook has been added to ~/.bashrc.
+Open a NEW shell (or run 'source ~/.bashrc'), then:
+  micromamba activate $ENV_NAME
+
+Verify:
+  west --version
+  echo \$ZEPHYR_BASE              # -> $WORKSPACE_DIR/zephyr
+
+For the CURRENT session without a new shell:
+  eval "\$("$MAMBA" shell hook --shell bash)"
+  micromamba activate $ENV_NAME
+
+Then a typeCAD/cuttlefish Zephyr build should discover west automatically:
+  cd <project> && npx cuttlefish build
+
+EOF

package/installer/lib/detect-platform.sh

@@ -0,0 +1,62 @@
+#!/usr/bin/env bash
+# ---------------------------------------------------------------------------
+# detect-platform.sh — map uname output to conda + Zephyr SDK platform tokens.
+# Sourced by install.sh. Defines detect_platform(), which exports:
+#
+#   MAMBA_PLAT   conda subdir:  linux-64 | linux-aarch64 | osx-64 | osx-arm64 | win-64
+#   SDK_PLAT     Zephyr SDK bundle platform: linux-x86_64 | linux-aarch64 |
+#                macos-x86_64 | macos-aarch64 | windows-x86_64
+#   ARCHIVE_EXT  archive type for the SDK bundle: tar.xz (POSIX) | 7z (Windows)
+#
+# Returns non-zero on unsupported platforms. The conda arch token is OS-
+# dependent (x86_64 -> "64" everywhere; arm64 is "arm64" on macOS but
+# "aarch64" on Linux), so it is built from an explicit case table rather
+# than a string substitution.
+# ---------------------------------------------------------------------------
+
+detect_platform() {
+  local os arch
+  os="$(uname -s)"
+  arch="$(uname -m)"
+
+  local mamba_os sdk_os
+  case "$os" in
+    Linux*)                       mamba_os=linux; sdk_os=linux   ;;
+    Darwin*)                      mamba_os=osx;   sdk_os=macos   ;;
+    MINGW*|MSYS*|CYGWIN*)         mamba_os=win;   sdk_os=windows ;;
+    *)
+      echo "detect-platform: unsupported OS: $os (expected Linux, macOS, or Windows/Git Bash)" >&2
+      return 1
+      ;;
+  esac
+
+  local sdk_arch
+  case "$arch" in
+    x86_64|amd64)   sdk_arch=x86_64 ;;
+    aarch64|arm64)  sdk_arch=aarch64 ;;
+    *)
+      echo "detect-platform: unsupported arch: $arch (expected x86_64 or aarch64/arm64)" >&2
+      return 1
+      ;;
+  esac
+
+  case "${mamba_os}-${arch}" in
+    linux-x86_64|osx-x86_64|win-x86_64) MAMBA_PLAT="${mamba_os}-64" ;;
+    linux-aarch64|linux-arm64)          MAMBA_PLAT="linux-aarch64"  ;;
+    osx-arm64)                          MAMBA_PLAT="osx-arm64"      ;;
+    *)
+      echo "detect-platform: no conda subdir maps to ${mamba_os}-${arch}" >&2
+      return 1
+      ;;
+  esac
+
+  SDK_PLAT="${sdk_os}-${sdk_arch}"
+
+  if [ "$sdk_os" = "windows" ]; then
+    ARCHIVE_EXT="7z"
+  else
+    ARCHIVE_EXT="tar.xz"
+  fi
+
+  export MAMBA_PLAT SDK_PLAT ARCHIVE_EXT
+}

package/installer/lib/fetch-sdk.sh

@@ -0,0 +1,304 @@
+#!/usr/bin/env bash
+# ---------------------------------------------------------------------------
+# fetch-sdk.sh — download, verify, and extract the Zephyr SDK.
+# Sourced by install.sh. Defines fetch_sdk(), which reads:
+#
+#   ZEPHYR_SDK_VERSION, SDK_RELEASE_BASE  (versions.env)
+#   SDK_PLAT, ARCHIVE_EXT                 (detect_platform)
+#   SHA256_<platform-with-underscores>    (versions.env; TODO = unpinned)
+#   SDK_INSTALL_PARENT                    (resolved by install.sh)
+#   DRY_RUN                               (install.sh flag)
+#   PLATFORMS                             (install.sh flag or install.mjs
+#                                          checklist — comma-separated group
+#                                          ids, or "all" for the full bundle)
+#
+# On success the SDK is extracted to $SDK_INSTALL_PARENT/zephyr-sdk-<version>/.
+#
+# SELECTIVE MODE (PLATFORMS != "all"): downloads the ~10MB minimal bundle
+# (cmake config + sdk_version) then only the selected toolchains
+# (~100-300MB per group). Idempotent per-toolchain: a target dir that already
+# exists is skipped, so --modify can add platforms incrementally without
+# re-downloading everything.
+#
+# We deliberately do NOT run the SDK's setup.sh: the Zephyr docs endorse
+# setting ZEPHYR_SDK_INSTALL_DIR as the alternative to setup.sh's CMake
+# registry registration. That avoids sudo, the interactive toolchain prompt,
+# and any host-tools install (host tools come from the conda env instead).
+# ---------------------------------------------------------------------------
+
+# Cross-platform sha256: sha256sum on Linux/Git Bash, shasum -a 256 on macOS.
+_compute_sha256() {
+  local file="$1"
+  if command -v sha256sum >/dev/null 2>&1; then
+    sha256sum "$file" | awk '{print $1}'
+  else
+    shasum -a 256 "$file" | awk '{print $1}'
+  fi
+}
+
+# Download helper shared by the bundle + toolchain paths.
+_download() {
+  local url="$1" archive="$2"
+  if command -v curl >/dev/null 2>&1; then
+    curl -fL --retry 3 -C - -o "$archive" "$url" \
+      || { echo "fetch-sdk: curl download failed" >&2; return 1; }
+  elif command -v wget >/dev/null 2>&1; then
+    wget -c -O "$archive" "$url" \
+      || { echo "fetch-sdk: wget download failed" >&2; return 1; }
+  else
+    echo "fetch-sdk: need curl or wget on PATH" >&2
+    return 1
+  fi
+}
+
+# Verify (skip with a computed-hash printout when not yet pinned).
+_verify() {
+  local archive="$1" expected="$2"
+  local actual
+  actual="$(_compute_sha256 "$archive")"
+  if [ "$expected" = "TODO" ] || [ -z "$expected" ]; then
+    echo "fetch-sdk: WARNING — SHA256 not pinned (TODO in versions.env); skipping verification." >&2
+    echo "fetch-sdk: computed sha256 (pin this in versions.env to enforce): $actual"
+  else
+    if [ "$actual" != "$expected" ]; then
+      echo "fetch-sdk: SHA256 mismatch!" >&2
+      echo "fetch-sdk:   expected: $expected" >&2
+      echo "fetch-sdk:   actual:   $actual" >&2
+      rm -f "$archive"
+      return 1
+    fi
+    echo "fetch-sdk: sha256 OK ($actual)"
+  fi
+}
+
+# Extract helper. ARCHIVE_EXT is .tar.xz (POSIX) or .7z (Windows).
+_extract() {
+  local archive="$1" dest="$2"
+  case "$ARCHIVE_EXT" in
+    tar.xz)
+      tar -xf "$archive" -C "$dest" \
+        || { echo "fetch-sdk: tar extract failed" >&2; return 1; }
+      ;;
+    7z)
+      local sevenz
+      sevenz="$(command -v 7z || command -v 7za || true)"
+      if [ -z "$sevenz" ]; then
+        echo "fetch-sdk: need 7z to extract a .7z bundle" >&2
+        echo "fetch-sdk: the conda env provides it (7zip in environment.yml); activate the env first" >&2
+        return 1
+      fi
+      "$sevenz" x -y -o"$dest" "$archive" >/dev/null \
+        || { echo "fetch-sdk: 7z extract failed" >&2; return 1; }
+      ;;
+    *)
+      echo "fetch-sdk: unknown archive extension: $ARCHIVE_EXT" >&2
+      return 1
+      ;;
+  esac
+}
+
+# List installed toolchain targets by scanning a directory. Used by the
+# --modify delta (installed-but-not-selected → removed). The xtensa- prefixed
+# pattern matters: xtensa targets are multi-segment
+# (xtensa-espressif_esp32s3_zephyr-elf) and a single-segment regex misses them.
+_list_installed_toolchains() {
+  local dir="$1"
+  [ -d "$dir" ] || return 0
+  (cd "$dir" && ls -d */ 2>/dev/null | sed 's|/$||' | grep -E '^(xtensa-)?.*-zephyr-(eabi|elf)$' || true)
+}
+
+fetch_sdk() {
+  local sdk="$SDK_INSTALL_PARENT/zephyr-sdk-${ZEPHYR_SDK_VERSION}"
+  local platforms="${PLATFORMS:-all}"
+  # 1.0.x bundle flavor suffix (_gnu = all GNU toolchains + host tools); empty
+  # for 0.17.x "full" bundles. Individual toolchain tarballs carry the flavor
+  # as an infix (toolchain_gnu_<plat>_<target>) when set.
+  local suffix="${ZEPHYR_SDK_BUNDLE_SUFFIX:-}"
+  local tc_infix=""
+  [ -n "$suffix" ] && tc_infix="${suffix#_}_"
+  echo "fetch-sdk: platform selection: $platforms"
+
+  # ── FULL BUNDLE MODE (platforms = "all") ────────────────────────────────────
+  if [ "$platforms" = "all" ]; then
+    local bundle="zephyr-sdk-${ZEPHYR_SDK_VERSION}_${SDK_PLAT}${suffix}.${ARCHIVE_EXT}"
+    local url="${SDK_RELEASE_BASE}/v${ZEPHYR_SDK_VERSION}/${bundle}"
+    local checksum_var="SHA256_$(echo "$SDK_PLAT" | tr '-' '_')"
+    local expected="${!checksum_var:-TODO}"
+
+    if [ "$expected" = "NONE" ]; then
+      echo "fetch-sdk: ERROR — the Zephyr SDK ${ZEPHYR_SDK_VERSION} publishes no build for ${SDK_PLAT}." >&2
+      echo "fetch-sdk:   (macOS Intel has no 1.0.x SDK.) Use an ARM Mac, or pin the older" >&2
+      echo "fetch-sdk:   SDK line: --sdk-version 0.17.4" >&2
+      return 1
+    fi
+
+    echo "fetch-sdk: downloading full bundle $bundle"
+    echo "fetch-sdk:   url:    $url"
+    echo "fetch-sdk:   sha256: ${expected}"
+
+    if [ "$DRY_RUN" = "1" ]; then
+      echo "fetch-sdk: [DRY-RUN] would download $url"
+      echo "fetch-sdk: [DRY-RUN] would extract into $SDK_INSTALL_PARENT"
+      echo "fetch-sdk: [DRY-RUN] would set ZEPHYR_SDK_INSTALL_DIR=$sdk"
+      return 0
+    fi
+
+    if [ -e "$sdk/sdk_version" ]; then
+      echo "fetch-sdk: SDK already present at $sdk — skipping download"
+      return 0
+    fi
+
+    mkdir -p "$SDK_INSTALL_PARENT"
+    local archive="${SDK_INSTALL_PARENT}/${bundle}"
+    _download "$url" "$archive" || return 1
+    _verify "$archive" "$expected" || return 1
+    _extract "$archive" "$SDK_INSTALL_PARENT" || return 1
+    rm -f "$archive"
+    echo "fetch-sdk: done — $sdk"
+    return 0
+  fi
+
+  # ── SELECTIVE MODE (minimal bundle + individual toolchains) ─────────────────
+  local sel_checksum="SHA256_$(echo "$SDK_PLAT" | tr '-' '_')"
+  if [ "${!sel_checksum:-TODO}" = "NONE" ]; then
+    echo "fetch-sdk: ERROR — the Zephyr SDK ${ZEPHYR_SDK_VERSION} publishes no build for ${SDK_PLAT}." >&2
+    echo "fetch-sdk:   (macOS Intel has no 1.0.x SDK.) Use an ARM Mac, or pin the older" >&2
+    echo "fetch-sdk:   SDK line: --sdk-version 0.17.4" >&2
+    return 1
+  fi
+  local minimal="zephyr-sdk-${ZEPHYR_SDK_VERSION}_${SDK_PLAT}_minimal.${ARCHIVE_EXT}"
+  local minimal_url="${SDK_RELEASE_BASE}/v${ZEPHYR_SDK_VERSION}/${minimal}"
+
+  if [ "$DRY_RUN" = "1" ]; then
+    echo "fetch-sdk: [DRY-RUN] would download minimal bundle $minimal_url (~10 MB)"
+    echo "fetch-sdk: [DRY-RUN] selected platforms: $platforms"
+    local grp
+    for grp in ${platforms//,/ }; do
+      local targets_var="PLATFORM_${grp}"
+      echo "fetch-sdk: [DRY-RUN]   ${grp}: ${!targets_var:-<unknown group>}"
+    done
+    echo "fetch-sdk: [DRY-RUN] would write .typecad-platforms state file"
+    return 0
+  fi
+
+  mkdir -p "$SDK_INSTALL_PARENT"
+
+  # 1. Minimal bundle (cmake/ + sdk_version + sdk_toolchains — ~10 MB).
+  if [ -e "$sdk/sdk_version" ]; then
+    echo "fetch-sdk: SDK base already present at $sdk — skipping minimal bundle"
+  else
+    echo "fetch-sdk: downloading minimal bundle (~10 MB)"
+    local minimal_archive="${SDK_INSTALL_PARENT}/${minimal}"
+    _download "$minimal_url" "$minimal_archive" || return 1
+    # The minimal bundle's SHA256 is small enough that a mismatch is unlikely;
+    # verify if pinned but don't fail on TODO.
+    _verify "$minimal_archive" "TODO" || true
+    _extract "$minimal_archive" "$SDK_INSTALL_PARENT" || return 1
+    rm -f "$minimal_archive"
+  fi
+
+  # 1.0.x installs toolchains under <sdk>/gnu/ — the SDK's own setup.sh does
+  # `cd gnu && tar -x`, and its cmake globs ${ZEPHYR_SDK_INSTALL_DIR}/gnu/*
+  # (generic.cmake: TOOLCHAIN_HOME=${ZEPHYR_SDK_INSTALL_DIR}/gnu). 0.17.x used
+  # the SDK root. Toolchains misplaced at the root by older installers are
+  # migrated (moved) into gnu/ instead of re-downloaded. Idempotency checks
+  # <target>/bin — a bare <target>/ dir can be a hollow leftover of a failed
+  # setup.sh/setup.cmd toolchain download.
+  local tc_root="$sdk"
+  local sdk_ng=0
+  if [ -n "$suffix" ]; then
+    tc_root="$sdk/gnu"
+    sdk_ng=1
+  fi
+  mkdir -p "$tc_root"
+
+  # 2. Individual toolchains for each selected platform group.
+  local grp targets target
+  for grp in ${platforms//,/ }; do
+    local targets_var="PLATFORM_${grp}"
+    targets="${!targets_var:-}"
+    if [ -z "$targets" ]; then
+      echo "fetch-sdk: WARNING — unknown platform group '$grp' (no PLATFORM_${grp} in versions.env); skipping" >&2
+      continue
+    fi
+    echo "fetch-sdk: platform '${grp}':"
+    for target in $targets; do
+      # Migrate / clean a misplaced SDK-root copy from pre-1.0.x-layout installs.
+      if [ "$sdk_ng" -eq 1 ] && [ -d "$sdk/$target" ]; then
+        if [ -d "$tc_root/$target/bin" ]; then
+          echo "fetch-sdk:   $target — removing misplaced SDK-root copy (pre-1.0.x-layout install)"
+          rm -rf "$sdk/$target"
+        else
+          echo "fetch-sdk:   $target — migrating misplaced SDK-root copy into gnu/"
+          mv "$sdk/$target" "$tc_root/$target"
+        fi
+        continue
+      fi
+      if [ -d "$tc_root/$target/bin" ]; then
+        echo "fetch-sdk:   $target — already installed, skipping"
+        continue
+      fi
+      # A target dir without bin/ is a hollow leftover (e.g. a failed SDK
+      # setup.sh download) — remove it so the fresh extract lands clean.
+      if [ -d "$tc_root/$target" ]; then
+        echo "fetch-sdk:   $target — hollow toolchain dir (no bin/), re-downloading"
+        rm -rf "$tc_root/$target"
+      fi
+      # 1.0.x names individual toolchains toolchain_gnu_<plat>_<target>; 0.17.x
+      # used toolchain_<plat>_<target>. tc_infix carries the flavor when set.
+      local tc_bundle="toolchain_${tc_infix}${SDK_PLAT}_${target}.${ARCHIVE_EXT}"
+      local tc_url="${SDK_RELEASE_BASE}/v${ZEPHYR_SDK_VERSION}/${tc_bundle}"
+      echo "fetch-sdk:   $target — downloading ${tc_bundle}"
+      local tc_archive="${SDK_INSTALL_PARENT}/${tc_bundle}"
+      _download "$tc_url" "$tc_archive" || return 1
+      _verify "$tc_archive" "TODO" || true
+      # Toolchain archives are flat (<target>/bin/...); extract into the
+      # toolchain root (gnu/ on 1.0.x, the SDK root on 0.17.x).
+      _extract "$tc_archive" "$tc_root" || return 1
+      rm -f "$tc_archive"
+    done
+  done
+
+  # 3. --prune only: remove installed toolchains that are NOT in the new
+  #    selection. Without --prune the modify step is purely additive —
+  #    unselected toolchains stay on disk so an existing install never
+  #    loses anything because of a narrower re-run. On 1.0.x scan both the
+  #    gnu/ root and the SDK root so misplaced copies get cleaned up too.
+  if [ "${PRUNE:-0}" = "1" ]; then
+    local installed="$(_list_installed_toolchains "$tc_root")"
+    [ "$sdk_ng" -eq 1 ] && installed="$installed $(_list_installed_toolchains "$sdk")"
+    local selected_targets=""
+    for grp in ${platforms//,/ }; do
+      local targets_var="PLATFORM_${grp}"
+      selected_targets="$selected_targets ${!targets_var:-}"
+    done
+    for target in $installed; do
+      if ! echo " $selected_targets " | grep -q " $target "; then
+        echo "fetch-sdk: removing deselected toolchain: $target"
+        rm -rf "$tc_root/$target" "$sdk/$target"
+      fi
+    done
+  fi
+
+  # 4. Persist the selection. Without --prune the marker records the UNION
+  #    of what was here before and the new selection — the marker must
+  #    describe what is actually on disk.
+  local marker_path="$sdk/.typecad-platforms"
+  local marker_sel="$platforms"
+  if [ "${PRUNE:-0}" != "1" ] && [ -f "$marker_path" ]; then
+    local prev union="" seen="" grp
+    prev="$(cat "$marker_path")"
+    for grp in $(echo "$prev,$platforms" | tr ',' ' '); do
+      grp="$(echo "$grp" | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')"
+      [ -z "$grp" ] && continue
+      [ "$grp" = "all" ] && continue
+      case " $seen " in
+        *" $grp "*) ;;
+        *) seen="$seen $grp"; union="${union:+$union,}$grp" ;;
+      esac
+    done
+    [ -n "$union" ] && marker_sel="$union"
+  fi
+  echo "$marker_sel" > "$marker_path"
+  echo "fetch-sdk: done — $sdk (platforms: $marker_sel)"
+}