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

package/installer/lib/init-workspace.sh

@@ -0,0 +1,153 @@
+#!/usr/bin/env bash
+# ---------------------------------------------------------------------------
+# init-workspace.sh — west init + west update a vanilla Zephyr workspace.
+# Sourced by install.sh. Defines init_workspace(), which reads:
+#
+#   ZEPHYR_MANIFEST_URL, ZEPHYR_MANIFEST_REV  (versions.env)
+#   WORKSPACE_DIR                             (resolved by install.sh)
+#   ENV_NAME                                  (versions.env)
+#   MAMBA                                     (micromamba binary path, install.sh)
+#   MAMBA_ROOT_PREFIX                         (resolved by install.sh)
+#   DRY_RUN                                   (install.sh flag)
+#
+# Uses `west init -m <url> --mr <rev> <dir>` to pin the manifest to a specific
+# Zephyr tag, then `west update` to fetch zephyr + all manifest projects. The
+# resulting <WORKSPACE_DIR>/zephyr/ is what ZEPHYR_BASE points at.
+#
+# Idempotent: if <WORKSPACE_DIR>/.west already exists, skips init and only
+# updates. micromamba run -n runs west in the env without sourcing activation
+# hooks (west is found on the env's PATH); activation is the user's later step.
+# ---------------------------------------------------------------------------
+
+init_workspace() {
+  echo "init-workspace: west init $WORKSPACE_DIR"
+  echo "init-workspace:   manifest: $ZEPHYR_MANIFEST_URL @ $ZEPHYR_MANIFEST_REV"
+
+  if [ "$DRY_RUN" = "1" ]; then
+    echo "init-workspace: [DRY-RUN] would run: $MAMBA run -n $ENV_NAME west init -m $ZEPHYR_MANIFEST_URL --mr $ZEPHYR_MANIFEST_REV $WORKSPACE_DIR"
+    echo "init-workspace: [DRY-RUN] would run: $MAMBA run -n $ENV_NAME west update"
+    echo "init-workspace: [DRY-RUN] would set ZEPHYR_BASE=$WORKSPACE_DIR/zephyr"
+    return 0
+  fi
+
+  export MAMBA_ROOT_PREFIX
+  if [ -d "$WORKSPACE_DIR/.west" ] && [ -f "$WORKSPACE_DIR/.west/config" ]; then
+    echo "init-workspace: $WORKSPACE_DIR already initialized — running west update only"
+    # A workspace adopted from a pre-existing install (or initialized by an
+    # older installer) can track a branch or an older tag — plain `west update`
+    # never moves the manifest repository, so it drifts out of sync with the
+    # SDK this installer pins. Re-pin the revision AND check the tag out so
+    # west update below syncs modules against the pinned manifest.
+    if cur_rev="$(cd "$WORKSPACE_DIR" && "$MAMBA" run -n "$ENV_NAME" west config manifest.revision 2>/dev/null)"; then
+      :
+    else
+      cur_rev=""
+    fi
+    if [ "$cur_rev" != "$ZEPHYR_MANIFEST_REV" ]; then
+      echo "init-workspace: pinning manifest revision -> $ZEPHYR_MANIFEST_REV (was: ${cur_rev:-<unset - default branch>})"
+    fi
+    # All three steps are idempotent; they must also run when the config
+    # already says the right thing but the tree is still on the old revision.
+    (cd "$WORKSPACE_DIR" && "$MAMBA" run -n "$ENV_NAME" west config manifest.revision "$ZEPHYR_MANIFEST_REV") \
+      || { echo "init-workspace: west config manifest.revision failed" >&2; return 1; }
+    "$MAMBA" run -n "$ENV_NAME" git -C "$WORKSPACE_DIR/zephyr" fetch origin "refs/tags/$ZEPHYR_MANIFEST_REV:refs/tags/$ZEPHYR_MANIFEST_REV" \
+      || { echo "init-workspace: git fetch tag $ZEPHYR_MANIFEST_REV failed" >&2; return 1; }
+    "$MAMBA" run -n "$ENV_NAME" git -C "$WORKSPACE_DIR/zephyr" checkout "$ZEPHYR_MANIFEST_REV" \
+      || { echo "init-workspace: git checkout $ZEPHYR_MANIFEST_REV failed (dirty zephyr tree?)" >&2; return 1; }
+  else
+    if [ -d "$WORKSPACE_DIR/.west" ]; then
+      echo "init-workspace: $WORKSPACE_DIR/.west exists but its config is missing (interrupted init?) — re-initializing"
+      rm -rf "$WORKSPACE_DIR/.west"
+    fi
+    mkdir -p "$(dirname "$WORKSPACE_DIR")"
+    "$MAMBA" run -n "$ENV_NAME" west init -m "$ZEPHYR_MANIFEST_URL" --mr "$ZEPHYR_MANIFEST_REV" "$WORKSPACE_DIR" \
+      || { echo "init-workspace: west init failed" >&2; return 1; }
+  fi
+
+  # west update pulls zephyr + all modules. Slow the first time (large clone).
+  echo "init-workspace: running west update (this fetches zephyr + modules)..."
+  "$MAMBA" run -n "$ENV_NAME" west update \
+    || { echo "init-workspace: west update failed" >&2; return 1; }
+
+  # Workspace patches — upstream fixes the pinned manifest revisions don't
+  # carry yet (see patches/*.patch). `git apply --check` makes this
+  # idempotent: an already-applied (or already-upstreamed) patch is skipped,
+  # never a hard failure. Each patch carries a `# typecad-repo: <path>`
+  # header naming its workspace repo (first-directory guesses break on
+  # nested projects like modules/tee/tf-m/trusted-firmware-m).
+  if [ -d "$PKG_DIR/patches" ]; then
+    for patch in "$PKG_DIR"/patches/*.patch; do
+      [ -f "$patch" ] || continue
+      repo_name=$(grep -m1 '^# typecad-repo:' "$patch" | sed 's/^# typecad-repo:[[:space:]]*//')
+      if [ -z "$repo_name" ]; then
+        echo "init-workspace: WARNING: $(basename "$patch") — no 'typecad-repo:' header, skipping" >&2
+        continue
+      fi
+      repo_dir="$WORKSPACE_DIR/$repo_name"
+      if [ ! -d "$repo_dir" ]; then
+        echo "init-workspace: WARNING: $(basename "$patch") — $repo_dir not present, skipping" >&2
+        continue
+      fi
+      echo "init-workspace: applying patch $(basename "$patch") to $repo_name..."
+      if git -C "$repo_dir" apply --check "$patch" 2>/dev/null; then
+        git -C "$repo_dir" apply "$patch" \
+          || { echo "init-workspace: patch apply failed: $(basename "$patch")" >&2; return 1; }
+      else
+        echo "init-workspace:   already applied (or inapplicable) — skipping"
+      fi
+    done
+  fi
+
+  # Install Zephyr's pinned Python build deps (jsonschema, pykwalify, PyYAML,
+  # intelhex, canopen, ...) into the env. CMake checks for these and the build
+  # fails with e.g. "Missing jsonschema dependency" without them. Letting
+  # Zephyr's own requirements file drive this avoids chasing deps one-by-one
+  # and tracks the pinned Zephyr revision.
+  echo "init-workspace: installing Zephyr Python requirements (requirements-base.txt)..."
+  "$MAMBA" run -n "$ENV_NAME" pip install -r "$WORKSPACE_DIR/zephyr/scripts/requirements-base.txt" \
+    || { echo "init-workspace: pip install requirements failed" >&2; return 1; }
+
+  # imgtool — MCUboot's signing tool. Not in requirements-base.txt, but TF-M /
+  # FVP signing steps invoke it as a module (mps4 corstone builds fail with
+  # "No module named 'imgtool'" without it).
+  echo "init-workspace: installing imgtool (MCUboot signing tool)..."
+  "$MAMBA" run -n "$ENV_NAME" pip install imgtool \
+    || echo "init-workspace: WARNING: imgtool install failed — TF-M/FVP signing will not work" >&2
+
+  # TF-M secure-build tooling: the inner TF-M build's bl2_image_config step
+  # parses compile_commands (needs the `clang` python bindings) and Nordic's
+  # RTE_Device.h needs devicetree headers — requirements + libclang (native
+  # library the python `clang` bindings load) from conda-forge.
+  tfm_tools="$WORKSPACE_DIR/modules/tee/tf-m/trusted-firmware-m/tools/requirements.txt"
+  if [ -f "$tfm_tools" ]; then
+    echo "init-workspace: installing TF-M tools requirements..."
+    "$MAMBA" run -n "$ENV_NAME" pip install -r "$tfm_tools" >/dev/null 2>&1 \
+      || echo "init-workspace:   WARNING: TF-M tools requirements install failed" >&2
+  fi
+  echo "init-workspace: installing libclang (conda-forge)..."
+  "$MAMBA" install -n "$ENV_NAME" -c conda-forge libclang -y \
+    || echo "init-workspace:   WARNING: libclang install failed — TF-M bl2 config step will fail" >&2
+
+  # Build-relevant per-module Python requirements ONLY. A bare `find -name
+  # requirements.txt` would also pull docs/test/harness/example requirements
+  # (mbedtls docs, openthread harness, cmsis tests, lvgl docs, tf-m tools) — heavy
+  # and conflict-prone. Restrict to locations holding actual build tooling: HAL
+  # scripts/zephyr dirs (esptool for espressif, vendor flash/script tools) and
+  # top-level lib codegen (nanopb, zcbor). Board support itself is universal —
+  # west fetched every module and the SDK ships every cross-toolchain — so these
+  # are the few extras a build needs beyond requirements-base.txt.
+  echo "init-workspace: installing per-module Python requirements (build tooling only)..."
+  for req in \
+    "$WORKSPACE_DIR"/modules/hal/*/scripts/requirements.txt \
+    "$WORKSPACE_DIR"/modules/hal/*/zephyr/requirements.txt \
+    "$WORKSPACE_DIR"/modules/lib/*/requirements.txt \
+    "$WORKSPACE_DIR"/modules/lib/*/scripts/requirements.txt
+  do
+    [ -f "$req" ] || continue
+    echo "init-workspace:   module requirements: ${req#"$WORKSPACE_DIR"/}"
+    "$MAMBA" run -n "$ENV_NAME" pip install -r "$req" >/dev/null 2>&1 \
+      || echo "init-workspace:   WARNING: module requirements install failed: $req" >&2
+  done
+
+  echo "init-workspace: done — ZEPHYR_BASE=$WORKSPACE_DIR/zephyr"
+}

package/installer/lib/write-activation.sh

@@ -0,0 +1,76 @@
+#!/usr/bin/env bash
+# ---------------------------------------------------------------------------
+# write-activation.sh — install conda activation/deactivation hooks into the env.
+# Sourced by install.sh. Defines write_activation(), which reads:
+#
+#   ENV_PREFIX                             (resolved by install.sh: env root)
+#   WORKSPACE_DIR                          (resolved by install.sh)
+#   ZEPHYR_SDK_INSTALL_DIR                 (resolved by install.sh)
+#   PKG_DIR                                (install.sh: this package's root)
+#   ZEPHYR_SDK_VERSION                     (versions.env)
+#   DRY_RUN                                (install.sh flag)
+#
+# Writes three env-vars files (sh / bat / ps1) carrying the RESOLVED paths,
+# then copies the static hooks from etc/conda/ into the env prefix. The hooks
+# are shell-agnostic boilerplate that only source env-vars.* and export
+# ZEPHYR_BASE + ZEPHYR_SDK_INSTALL_DIR — the per-machine values live in one
+# editable file per shell, so re-pointing the SDK never touches hook logic.
+#
+# Why this makes framework-zephyr work with zero code changes: when the env is
+# activated, west (from the conda env) is on PATH and ZEPHYR_BASE is exported,
+# so west-discover.ts's discoverFromPath() (Strategy 1) wins immediately and
+# returns the correct zephyrBase.
+# ---------------------------------------------------------------------------
+
+write_activation() {
+  local act_dst="$ENV_PREFIX/etc/conda/activate.d"
+  local deact_dst="$ENV_PREFIX/etc/conda/deactivate.d"
+  local zb="$WORKSPACE_DIR/zephyr"
+
+  echo "write-activation: hooks -> $act_dst / $deact_dst"
+
+  if [ "$DRY_RUN" = "1" ]; then
+    echo "write-activation: [DRY-RUN] would write env-vars.{sh,bat,ps1} to $ENV_PREFIX/etc/conda/"
+    echo "write-activation: [DRY-RUN] would copy activate.d/zephyr.{sh,bat,ps1} + deactivate.d/zephyr.{sh,bat,ps1}"
+    echo "write-activation: [DRY-RUN] ZEPHYR_BASE=$zb  ZEPHYR_SDK_INSTALL_DIR=$ZEPHYR_SDK_INSTALL_DIR"
+    return 0
+  fi
+
+  mkdir -p "$act_dst" "$deact_dst"
+
+  # POSIX (bash/zsh) — sourced by activate.d/zephyr.sh
+  cat > "$ENV_PREFIX/etc/conda/env-vars.sh" <<EOF
+# Resolved by the typeCAD Zephyr installer. Sourced by etc/conda/activate.d/zephyr.sh.
+# Edit these two paths to re-point the workspace or SDK without touching the hooks.
+export TYPECAD_ZEPHYR_BASE="$zb"
+export TYPECAD_ZEPHYR_SDK_INSTALL_DIR="$ZEPHYR_SDK_INSTALL_DIR"
+EOF
+
+  # cmd.exe — called by activate.d/zephyr.bat
+  cat > "$ENV_PREFIX/etc/conda/env-vars.bat" <<EOF
+@echo off
+REM Resolved by the typeCAD Zephyr installer. Called by etc/conda/activate.d/zephyr.bat.
+set "TYPECAD_ZEPHYR_BASE=$zb"
+set "TYPECAD_ZEPHYR_SDK_INSTALL_DIR=$ZEPHYR_SDK_INSTALL_DIR"
+EOF
+
+  # PowerShell — dot-sourced by activate.d/zephyr.ps1.
+  # NB: backslash-escape the $ in $env: (\$env:) — in an UNQUOTED heredoc a
+  # backtick is command substitution, not an escape, so `` `$env `` would try to
+  # expand the unbound `env` under `set -u` and abort. \$ produces a literal $.
+  cat > "$ENV_PREFIX/etc/conda/env-vars.ps1" <<EOF
+# Resolved by the typeCAD Zephyr installer. Dot-sourced by etc/conda/activate.d/zephyr.ps1.
+\$env:TYPECAD_ZEPHYR_BASE = "$zb"
+\$env:TYPECAD_ZEPHYR_SDK_INSTALL_DIR = "$ZEPHYR_SDK_INSTALL_DIR"
+EOF
+
+  # Static hooks (shell-agnostic; they only read env-vars.*).
+  cp "$PKG_DIR/etc/conda/activate.d/zephyr.sh"   "$act_dst/zephyr.sh"
+  cp "$PKG_DIR/etc/conda/activate.d/zephyr.bat"  "$act_dst/zephyr.bat"
+  cp "$PKG_DIR/etc/conda/activate.d/zephyr.ps1"  "$act_dst/zephyr.ps1"
+  cp "$PKG_DIR/etc/conda/deactivate.d/zephyr.sh"   "$deact_dst/zephyr.sh"
+  cp "$PKG_DIR/etc/conda/deactivate.d/zephyr.bat"  "$deact_dst/zephyr.bat"
+  cp "$PKG_DIR/etc/conda/deactivate.d/zephyr.ps1"  "$deact_dst/zephyr.ps1"
+
+  echo "write-activation: done"
+}

package/installer/patches/tfm-c-include-separators.patch

@@ -0,0 +1,19 @@
+# typecad-repo: modules/tee/tf-m/trusted-firmware-m
+# Applied by the typeCAD installer after west update (git apply --check guarded).
+diff --git a/tools/modules/c_include.py b/tools/modules/c_include.py
+index 636f31dd0..2ea02646e 100644
+--- a/tools/modules/c_include.py
++++ b/tools/modules/c_include.py
+@@ -13,7 +13,11 @@ def get_compile_command(compile_commands_file, c_file):
+     with open(compile_commands_file, "rt") as f:
+         compile_commands = json.load(f)
+ 
+-    return [x['command'] for x in compile_commands if c_file in x['file']][0]
++    # Match on normalized separators: on Windows x['file'] carries
++    # backslashes while callers pass forward-slash names ("bl1_2/main.c"),
++    # and the raw substring match then finds nothing (IndexError downstream).
++    return [x['command'] for x in compile_commands
++            if os.path.normpath(c_file) in os.path.normpath(x['file'])][0]
+ 
+ def get_includes(compile_commands_file, c_file):
+     compile_command = get_compile_command(compile_commands_file, c_file).split()

package/installer/patches/zephyr-tfm-nordic-zephyr-include.patch

@@ -0,0 +1,24 @@
+# typecad-repo: zephyr
+# Applied by the typeCAD installer after west update (git apply --check guarded).
+diff --git a/modules/trusted-firmware-m/nordic/CMakeLists.txt b/modules/trusted-firmware-m/nordic/CMakeLists.txt
+index 48b0a836e07..13b7e370481 100644
+--- a/modules/trusted-firmware-m/nordic/CMakeLists.txt
++++ b/modules/trusted-firmware-m/nordic/CMakeLists.txt
+@@ -10,10 +10,17 @@ set(CMAKE_CURRENT_SOURCE_DIR ${CMAKE_CURRENT_LIST_DIR})
+ set(partition_includes
+     ${Trusted\ Firmware\ M_SOURCE_DIR}/platform/ext/target/nordic_nrf/common/${NRF_SOC_VARIANT}/partition
+     ${CMAKE_BINARY_DIR}/../zephyr/include/generated
++    # RTE_Device.h (this dir) includes <zephyr/devicetree.h>, which lives in
++    # the zephyr SOURCE tree — the forwarded generated/ dirs above do not
++    # carry it. Upstream on Windows the secure/bl2 build (Driver_Flash.c)
++    # fails with "zephyr/devicetree.h: No such file or directory" without
++    # this; ZEPHYR_BASE is inherited from the outer build's environment.
++    $ENV{ZEPHYR_BASE}/include
+ )
+ 
+ set(board_includes
+     ${CMAKE_BINARY_DIR}/../zephyr/misc/generated/syscalls_links/include
++    $ENV{ZEPHYR_BASE}/include
+ )
+ 
+ target_include_directories(platform_region_defs

package/installer/templates/project/.typecad/activate-zephyr.ps1

@@ -0,0 +1,31 @@
+# ---------------------------------------------------------------------------
+# typeCAD Zephyr - per-project env activator (PowerShell).
+#
+# Run:     . .\.typecad\activate-zephyr.ps1
+# Auto-run on terminal open: see .vscode/settings.json in this template.
+#
+# Activates the micromamba env created by the typeCAD Zephyr installer. After
+# activation, `west` is on PATH and ZEPHYR_BASE / ZEPHYR_SDK_INSTALL_DIR point
+# at the new install, so `npx cuttlefish build` uses it automatically.
+#
+# Override the env name with $TYPECAD_ZEPHYR_ENV (default: "zephyr").
+# ---------------------------------------------------------------------------
+$ErrorActionPreference = 'Stop'
+$EnvName = if ($env:TYPECAD_ZEPHYR_ENV) { $env:TYPECAD_ZEPHYR_ENV } else { 'zephyr' }
+
+# Load the micromamba shell hook if it isn't already available (e.g. this shell
+# was launched with -NoProfile, or shell init hasn't been run on this machine).
+if (-not (Get-Command micromamba -ErrorAction SilentlyContinue)) {
+  $mm = Join-Path $env:USERPROFILE 'micromamba\Library\bin\micromamba.exe'
+  if (-not (Test-Path $mm)) {
+    throw "micromamba not found at $mm. Run the typeCAD Zephyr installer first: node packages/framework-zephyr/installer/install.mjs"
+  }
+  # NB: the `| Invoke-Expression` pipe form fails under PowerShell (it parses
+  # the multi-line hook line-by-line). Capture as an array, join with newlines.
+  Invoke-Expression ((& $mm shell hook -s powershell) -join [char]10)
+}
+
+micromamba activate $EnvName
+
+Write-Host "typeCAD Zephyr: activated '$EnvName' -> $((Get-Command west -ErrorAction SilentlyContinue).Source)" -ForegroundColor DarkGray
+Write-Host "  ZEPHYR_BASE = $env:ZEPHYR_BASE" -ForegroundColor DarkGray

package/installer/templates/project/.typecad/activate-zephyr.sh

@@ -0,0 +1,31 @@
+# ---------------------------------------------------------------------------
+# typeCAD Zephyr - per-project env activator (bash / zsh).
+#
+# Source:   source .typecad/activate-zephyr.sh
+# Auto-run on terminal open: use direnv (.envrc -> source this file) or a VS
+# Code bash terminal profile with --rcfile.
+#
+# Activates the micromamba env created by the typeCAD Zephyr installer. After
+# activation, `west` is on PATH and ZEPHYR_BASE / ZEPHYR_SDK_INSTALL_DIR point
+# at the new install, so `npx cuttlefish build` uses it automatically.
+#
+# Override the env name with $TYPECAD_ZEPHYR_ENV (default: "zephyr").
+# ---------------------------------------------------------------------------
+EnvName="${TYPECAD_ZEPHYR_ENV:-zephyr}"
+
+# Load the micromamba shell hook if it isn't already on PATH.
+if ! command -v micromamba >/dev/null 2>&1; then
+  mm="$HOME/micromamba/bin/micromamba"
+  if [ ! -x "$mm" ]; then
+    echo "micromamba not found at $mm. Run the typeCAD Zephyr installer first:" >&2
+    echo "  node packages/framework-zephyr/installer/install.mjs" >&2
+    # `return` when sourced, `exit` when executed.
+    return 1 2>/dev/null || exit 1
+  fi
+  eval "$("$mm" shell hook --shell bash)"
+fi
+
+micromamba activate "$EnvName"
+
+echo "typeCAD Zephyr: activated '$EnvName' -> $(command -v west)"
+echo "  ZEPHYR_BASE = $ZEPHYR_BASE"

package/installer/templates/project/.vscode/settings.json

@@ -0,0 +1,30 @@
+// ---------------------------------------------------------------------------
+// typeCAD Zephyr - VS Code terminal auto-activation (Windows).
+//
+// New integrated terminals launch the "zephyr-powershell" profile, which runs
+// .typecad/activate-zephyr.ps1 (-NoExit keeps the shell open afterward). This
+// makes `micromamba activate zephyr` happen automatically, so `west` is on
+// PATH and ZEPHYR_BASE / ZEPHYR_SDK_INSTALL_DIR are set without per-session
+// typing - and `npx cuttlefish build` uses the new install.
+//
+// If this project already has a .vscode/settings.json, MERGE these keys into
+// it by hand rather than overwriting the whole file.
+//
+// To make activation OPT-IN (pick "zephyr-powershell" from the terminal
+// dropdown) instead of automatic, delete the "defaultProfile.windows" line.
+// Do that in multi-framework workspaces (e.g. the typecode monorepo, which
+// also does ESP-IDF/Arduino) so this doesn't clash with other toolchains.
+// ---------------------------------------------------------------------------
+{
+  "terminal.integrated.defaultProfile.windows": "zephyr-powershell",
+  "terminal.integrated.profiles.windows": {
+    "zephyr-powershell": {
+      // Prefer PowerShell 7 if installed; fall back to Windows PowerShell 5.1.
+      "path": [
+        "${env:ProgramFiles}\\PowerShell\\7\\pwsh.exe",
+        "${env:WINDIR}\\System32\\WindowsPowerShell\\v1.0\\powershell.exe"
+      ],
+      "args": ["-NoExit", "-File", "${workspaceFolder}\\.typecad\\activate-zephyr.ps1"]
+    }
+  }
+}

package/installer/templates/project/README.md

@@ -0,0 +1,58 @@
+# typeCAD Zephyr — per-project activation template
+
+Copy these files into a cuttlefish Zephyr project so that opening a terminal in
+it auto-activates the micromamba env created by the typeCAD Zephyr installer.
+Once active, `west` is on PATH and `ZEPHYR_BASE` / `ZEPHYR_SDK_INSTALL_DIR` are
+set, so `npx cuttlefish build` uses the new install automatically — no
+per-session `micromamba activate` typing.
+
+## Files
+
+| File | Role |
+| --- | --- |
+| `.typecad/activate-zephyr.ps1` | Windows activator. Run: `. .\.typecad\activate-zephyr.ps1` |
+| `.typecad/activate-zephyr.sh` | POSIX activator (bash/zsh). Source: `source .typecad/activate-zephyr.sh` |
+| `.vscode/settings.json` | VS Code terminal profile that auto-runs the Windows activator on every new terminal |
+
+Both activators are **machine-agnostic** — they find micromamba via
+`$USERPROFILE\micromamba\…` / `$HOME/micromamba/…` and the env name, so the
+same files work across machines with no hardcoded absolute paths.
+
+## Install into a project
+
+From the project root:
+
+```sh
+cp -r packages/framework-zephyr/installer/templates/project/.typecad ./
+mkdir -p .vscode
+cp    packages/framework-zephyr/installer/templates/project/.vscode/settings.json ./.vscode/settings.json
+```
+
+If the project **already** has a `.vscode/settings.json`, **merge** the
+`terminal.integrated.*` keys in by hand — don't overwrite the whole file.
+
+## Default vs. opt-in
+
+The shipped `settings.json` sets `terminal.integrated.defaultProfile.windows` so
+activation is **automatic** on every new terminal — correct for a dedicated
+Zephyr project. In a **multi-framework** workspace (e.g. the typecode monorepo,
+which also does ESP-IDF/Arduino), delete the `defaultProfile.windows` line so
+the profile is opt-in via the terminal dropdown instead — otherwise every
+terminal inherits the Zephyr env and clashes with the other toolchains.
+
+## macOS / Linux
+
+VS Code terminal auto-activation on POSIX isn't wired here (the Windows path is
+where the activation friction was highest). Two options:
+
+- **direnv** (recommended): add a `.envrc` to the project containing
+  `source .typecad/activate-zephyr.sh`. direnv auto-sources it on `cd` in.
+- A VS Code bash terminal profile using `--rcfile` that sources both
+  `~/.bashrc` and the activator.
+
+The `.sh` activator is safe to source repeatedly and is direnv-compatible.
+
+## Override the env name
+
+Set `TYPECAD_ZEPHYR_ENV` before activating to target a differently-named env
+(default: `zephyr`), e.g. if you maintain multiple SDK versions side by side.

package/installer/versions.env

@@ -0,0 +1,110 @@
+# ---------------------------------------------------------------------------
+# typeCAD Zephyr installer — pinned versions & download URLs.
+#
+# Single source of truth, sourced by install.sh / install.ps1 / the test suite.
+# Keep this shell-sourceable (KEY=value, no spaces around =, quote anything with
+# special characters). Path defaults that need ${HOME} expansion live in the
+# install scripts, not here — this file holds only versions and URLs.
+#
+# To upgrade the SDK or the Zephyr manifest, change the two values below and
+# re-run install.sh. The SHA256 fields should be filled in from the installer's
+# post-download output (the SDK 0.17.x line ships no checksum file; we pin the
+# hash directly for reproducibility). A value of TODO skips verification with a
+# warning — fill it in after your first verified download.
+# ---------------------------------------------------------------------------
+
+# Official Zephyr SDK. 1.0.x dropped "full" bundles: the _gnu bundle = all GNU
+# toolchains + host tools (the previous "full" equivalent). Zephyr 4.4 needs
+# SDK 1.0.x; Zephyr 4.3.x works with 0.17.x (--sdk-version 0.17.4).
+ZEPHYR_SDK_VERSION=1.0.1
+ZEPHYR_SDK_BUNDLE_SUFFIX=_gnu
+SDK_RELEASE_BASE=https://github.com/zephyrproject-rtos/sdk-ng/releases/download
+
+# Vanilla Zephyr west manifest (the local west workspace is initialized from this).
+ZEPHYR_MANIFEST_URL=https://github.com/zephyrproject-rtos/zephyr.git
+ZEPHYR_MANIFEST_REV=v4.4.2
+
+# micromamba (single static binary) — micro.mamba.pm redirects to the latest
+# build for the requested conda platform subdir.
+MICROMAMBA_BASE=https://micro.mamba.pm/api/micromamba
+
+# Name of the conda/mamba environment the installer creates.
+ENV_NAME=zephyr
+
+# dfu-util (Windows only) — west flash's dfu-util runner (STM32 ROM DFU
+# bootloader boards, e.g. the WeAct Black Pill) shells out to dfu-util; the
+# tool must be on PATH or the runner dies with a raw FileNotFoundError.
+# conda-forge has no dfu-util build, so the Windows installer fetches MSYS2's
+# mingw64 packages (dfu-util + its libusb / libwinpthread runtime DLLs) and
+# unpacks them into the env's Libraryin — on the activation PATH and on the
+# PATH of the `micromamba run -n zephyr west flash` the framework spawns.
+# install.sh (POSIX) installs via the system package manager instead.
+# NOTE: MSYS2 prunes superseded package versions from the repo — bump these
+# together (name + hash) when a refresh 404s, and verify the new SHA256.
+MSYS2_MINGW64_BASE=https://repo.msys2.org/mingw/mingw64
+DFU_UTIL_PKG=mingw-w64-x86_64-dfu-util-0.11-2
+DFU_UTIL_PKG_SHA256=950652382f6632ac4b7e42d39d0cda19ef593f1a490c56c814e9f65a5aabe89c
+LIBUSB_PKG=mingw-w64-x86_64-libusb-1.0.30-1
+LIBUSB_PKG_SHA256=124edc26b009678a4c5e759481a364abf63ed7f2f49a53092e8bd0a47c0c0740
+LIBWINPTHREAD_PKG=mingw-w64-x86_64-libwinpthread-14.0.0.r98.g19f5121a2-1
+LIBWINPTHREAD_PKG_SHA256=565a7ac155098633ce66096c02c98f274127111758fd25d3f0e5451c4cd21120
+
+# bossac (Windows only) — west flash's bossac runner (SAMD SAM-BA bootloader
+# boards — the Arduino Nano 33 IoT, Zero, MKR series) shells out to bossac,
+# and FindHostTools resolves find_program(BOSSAC) at build-configure time; a
+# missing binary bakes BOSSAC-NOTFOUND into the runner args and west flash
+# dies with "required program bossac not found". bossac is in neither the
+# Zephyr SDK nor conda-forge; the official upstream MSI extracts cleanly
+# with 7z and ships a self-contained bossac.exe (system DLLs only).
+BOSSA_URL=https://github.com/shumatech/BOSSA/releases/download/1.9.1/bossa-x64-1.9.1.msi
+BOSSA_SHA256=d6e8fe3a4ef4c31cfecbf8a4c0b52bfc07cf1dff11fb3f565c8ea5d8f7b94a17
+
+# Per-platform SHA256 of the SDK bundle, from the release's official sha256.sum
+# (1.0.x publishes one; for 0.17.x these were computed on first download).
+# TODO = not yet pinned; the fetch step skips verification and prints the
+# computed hash so you can pin it. NONE = no build exists for that platform
+# (macOS Intel has no 1.0.x SDK) — the fetch step fails with guidance.
+# Bundle filenames: zephyr-sdk-${ZEPHYR_SDK_VERSION}_${platform}${ZEPHYR_SDK_BUNDLE_SUFFIX}.${ext}
+# (minimal bundle: zephyr-sdk-..._${platform}_minimal.${ext}, unchanged by 1.0.x)
+SHA256_linux_x86_64=37a8c5b5569c2b482d39099c65fe3ddac4e43524996c731907e1e9f5818cbba7
+SHA256_linux_aarch64=6e38018f70af5e90c18cc04c2f8ac5a91c99f5559b25692d1b0de328c3edb88a
+SHA256_macos_x86_64=NONE
+SHA256_macos_aarch64=3dc6346a5888ebbcee19801bf6271627f04819778fe0ef3c7f3c7528e8f4ef2a
+SHA256_windows_x86_64=811cb97797ddf6198eea66b030168d12512f605c7e332ea24d2cbe47b769c472
+
+# ---------------------------------------------------------------------------
+# Platform groups — user-facing toolchain selection.
+#
+# The sdk-ng release publishes individual toolchain tarballs
+# (toolchain_${platform}_${target}.${ext}) and a minimal bundle
+# (zephyr-sdk-${version}_${platform}_minimal.${ext} — cmake config +
+# sdk_version, no toolchains, ~10MB). The full 1.5GB bundle ships every
+# toolchain; most users need only one group (~100-300MB).
+#
+# Each PLATFORM_<id> maps a user-facing group to its toolchain targets.
+# install.mjs presents these as the interactive checklist; --platforms
+# accepts comma-separated group ids, or "all" for the full bundle.
+# ---------------------------------------------------------------------------
+PLATFORM_arm="arm-zephyr-eabi"
+PLATFORM_esp32="xtensa-espressif_esp32_zephyr-elf xtensa-espressif_esp32s2_zephyr-elf xtensa-espressif_esp32s3_zephyr-elf"
+PLATFORM_riscv="riscv64-zephyr-elf"
+PLATFORM_arc="arc-zephyr-elf"
+PLATFORM_rx="rx-zephyr-elf"
+PLATFORM_x86="x86_64-zephyr-elf"
+PLATFORM_aarch64="aarch64-zephyr-elf"
+# Human labels for the checklist (shown by install.mjs).
+PLATFORM_arm_LABEL="ARM Cortex-M (nRF, RP2040, STM32, SAMD, ...)"
+PLATFORM_esp32_LABEL="ESP32 / ESP32-S2 / ESP32-S3 (Xtensa)"
+PLATFORM_riscv_LABEL="RISC-V (ESP32-C3/C6, generic RISC-V)"
+PLATFORM_arc_LABEL="ARC EM / HS (DesignWare EMSDP, IoT devkits, ...)"
+PLATFORM_rx_LABEL="Renesas RX (RX261, RX72N, ...)"
+PLATFORM_x86_LABEL="x86 / native_sim"
+PLATFORM_aarch64_LABEL="aarch64 (Cortex-A: FVP, BeaglePlay A53, ...)"
+# Approximate download size per group (shown in the checklist summary).
+PLATFORM_arm_SIZE="~150 MB"
+PLATFORM_esp32_SIZE="~300 MB"
+PLATFORM_riscv_SIZE="~120 MB"
+PLATFORM_arc_SIZE="~180 MB"
+PLATFORM_rx_SIZE="~150 MB"
+PLATFORM_x86_SIZE="~100 MB"
+PLATFORM_aarch64_SIZE="~100 MB"

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@typecad/framework-zephyr",
-  "version": "1.0.0-alpha.13",
-  "description": "TypeCAD framework package for the Zephyr RTOS — west/CMake build, devicetree-driven GPIO",
+  "version": "1.0.0-alpha.15",
+  "description": "TypeCAD framework package for the Zephyr RTOS \u2014 west/CMake build, devicetree-driven GPIO",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -19,30 +19,30 @@
       "default": "./dist/framework.manifest.js"
     }
   },
+  "bin": {
+    "zephyr-installer": "installer/install.mjs",
+    "typecad-zephyr-install": "installer/install.mjs"
+  },
   "files": [
     "dist",
-    "src"
+    "src",
+    "installer"
   ],
   "scripts": {
     "build": "tsc",
     "prepublishOnly": "npm run build",
-    "test": "vitest run --root ../.. tests/packages/framework-zephyr/manifest.test.ts",
+    "test": "vitest run --root ../.. tests/packages/framework-zephyr/manifest.test.ts tests/packages/framework-zephyr/installer-tests/",
     "test:coverage": "npm test && tsx ../../scripts/render-framework-coverage.ts",
-    "test:hw": "npm exec -- cuttlefish-test",
-    "test:hw:basics": "npm exec -- cuttlefish-test tests/01-basics.test.ts",
-    "test:hw:gpio": "npm exec -- cuttlefish-test tests/40-gpio.test.ts",
-    "test:hw:timers": "npm exec -- cuttlefish-test tests/42-timers.test.ts",
-    "test:http": "tsx ../../tests/hardware/start-server.ts",
-    "test:hw:http": "cd ../../tests/hardware && npm exec -- cuttlefish-test http-client.test.ts",
-    "test:mqtt": "tsx ../../tests/hardware/start-server.ts",
-    "test:hw:mqtt": "cd ../../tests/hardware && npm exec -- cuttlefish-test mqtt-client.test.ts"
+    "hal": "node hal/run.mjs",
+    "setup": "node installer/install.mjs",
+    "dry-run": "node installer/install.mjs --dry-run"
   },
   "dependencies": {
-    "@typecad/cuttlefish": "1.0.0-alpha.13"
+    "@typecad/cuttlefish": "1.0.0-alpha.15",
+    "@typecad/hal": "1.0.0-alpha.15"
   },
   "devDependencies": {
-    "@typecad/expect": "1.0.0-alpha.13",
-    "@typecad/board-xiao-nrf52840": "1.0.0-alpha.13",
+    "@typecad/expect": "1.0.0-alpha.15",
     "typescript": "^5.7.3"
   },
   "license": "MIT",
@@ -75,7 +75,7 @@
     "zephyr"
   ],
   "engines": {
-    "node": ">=18"
+    "node": ">=22.11.0"
   },
   "author": "typecad0",
   "sideEffects": false