Add board CLI workflow test; pick .bin vs .uf2 and fix put -r, romfs, mpy-cross.

Author: bdbarnett

AGENTS.md

@@ -8,6 +8,7 @@ npm install
 npm run compile          # tsc
 npm run lint             # tsc --noEmit
 npm run test:python      # unittest under cli/tests
+python3 tools/test_cli_workflows.py   # attached boards; skip flash unless --install-latest-firmware
 npm run package          # VSIX via @vscode/vsce
 ```
 

cli/src/mpftp/cli.py

@@ -317,8 +317,13 @@ def _is_windows_python(python: str) -> bool:
 
 # Env vars a Windows child spawned from WSL silently does not receive unless
 # named in WSLENV — MICROPYPATH is the reported case (mpftp#12): a Windows
-# micropython/mpremote falls back to its own default lib path with no error.
-_WSLENV_FORWARD_VARS = ("MICROPYPATH",)
+# Windows python.exe spawned from WSL only sees env vars listed in WSLENV.
+# /l = one path, /p = path list (PYTHONPATH). Without PYTHONPATH, a checkout
+# CLI would spawn the pip-installed sidecar and ignore local edits.
+_WSLENV_FORWARD = (
+    ("MICROPYPATH", "l"),
+    ("PYTHONPATH", "p"),
+)
 
 
 def _wslenv_forwarded_env(python: str) -> Optional[dict]:
@@ -328,12 +333,12 @@ def _wslenv_forwarded_env(python: str) -> Optional[dict]:
     wsl = os.environ.get("WSL_DISTRO_NAME") or os.environ.get("WSL_INTEROP")
     if not wsl or not _is_windows_python(python):
         return None
-    to_forward = [v for v in _WSLENV_FORWARD_VARS if os.environ.get(v) is not None]
+    to_forward = [(v, flag) for v, flag in _WSLENV_FORWARD if os.environ.get(v) is not None]
     if not to_forward:
         return None
     existing = [e.strip() for e in os.environ.get("WSLENV", "").split(":") if e.strip()]
     already = {e.split("/")[0] for e in existing}
-    additions = [f"{v}/l" for v in to_forward if v not in already]
+    additions = [f"{v}/{flag}" for v, flag in to_forward if v not in already]
     if not additions:
         return None
     env = dict(os.environ)
@@ -675,26 +680,27 @@ def cmd_tree(ns: argparse.Namespace) -> None:
 
 
 def cmd_put(ns: argparse.Namespace) -> None:
-    data = Path(ns.local).read_bytes()
+    local = Path(ns.local)
     client, mode = get_client()
     try:
         ensure_device(client, ns.device, ns.baud)
         dest = ns.remote
         mpy = bool(getattr(ns, "mpy", False))
         verify = bool(getattr(ns, "verify", True))
-        if getattr(ns, "recursive", False) or Path(ns.local).is_dir():
+        if getattr(ns, "recursive", False) or local.is_dir():
             out(
                 client.call(
                     "fs_cp",
                     {
-                        "src": str(Path(ns.local).resolve()),
+                        "src": str(local.resolve()),
                         "dest": ":" + dest if not dest.startswith(":") else dest,
                         "verify": verify,
                         "mpy": mpy,
                     },
                 )
             )
             return
+        data = local.read_bytes()
         if mpy:
             # The board may compile to a different remote path (.py -> .mpy); the
             # source bytes on the CLI side aren't what ends up on the board, so
@@ -1398,6 +1404,8 @@ def cmd_firmware(ns: argparse.Namespace) -> None:
             extra += ["--version", ns.version]
         if getattr(ns, "preview", False):
             extra.append("--preview")
+        if getattr(ns, "uf2", False):
+            extra.append("--uf2")
         if getattr(ns, "force", False):
             extra.append("--force")
         res = _engine_stream("download", extra)
@@ -1840,6 +1848,11 @@ def build_parser() -> argparse.ArgumentParser:
     )
     fwdd.add_argument("--version", default="", help="Release version (e.g. 1.28.0)")
     fwdd.add_argument("--preview", action="store_true", help="Latest preview build")
+    fwdd.add_argument(
+        "--uf2",
+        action="store_true",
+        help="Prefer .uf2 (default: .bin for esp32 serial, .uf2 for rp2/samd)",
+    )
     fwdd.add_argument("--force", action="store_true", help="Refresh catalog cache")
     fwdd.set_defaults(func=cmd_firmware)
 

cli/src/mpftp/firmware.py

@@ -2575,6 +2575,7 @@ def progress(done: int, total: int) -> None:
             version=getattr(ns, "version", None) or None,
             preview=bool(getattr(ns, "preview", False)),
             mp_variant=mp_variant,
+            uf2=bool(getattr(ns, "uf2", False)),
         )
         emit_log(f"[mpftp] downloading {chosen['url']}")
         path = download_file(chosen["url"], progress=progress)
@@ -2723,6 +2724,11 @@ def add_mp(sp: argparse.ArgumentParser, required: bool = False) -> None:
     )
     dld.add_argument("--version", default="", help="release version (e.g. 1.28.0)")
     dld.add_argument("--preview", action="store_true", help="latest preview build")
+    dld.add_argument(
+        "--uf2",
+        action="store_true",
+        help="prefer .uf2 (default: .bin for esp32, .uf2 for rp2/samd)",
+    )
     dld.add_argument("--force", action="store_true", help="refresh catalog cache")
     dld.set_defaults(func=do_download)
 

cli/src/mpftp/firmware_download.py

@@ -410,15 +410,55 @@ def enrich_downloads_from_page(
     return {"": json_default}
 
 
+def artifact_kind(url: str) -> str:
+    """``bin`` / ``uf2`` from a firmware URL, else empty."""
+    u = (url or "").rsplit("?", 1)[0].lower()
+    if u.endswith(".uf2"):
+        return "uf2"
+    if u.endswith(".bin"):
+        return "bin"
+    return ""
+
+
+def preferred_artifact_kind(variant: dict[str, Any], *, uf2: bool = False) -> str:
+    """Which image serial vs UF2 flashing wants.
+
+    Espressif boards are written with esptool (``.bin``). rp2/samd (and an
+    explicit ``uf2=True``, e.g. ESP32-S3 + tinyuf2) want ``.uf2``.
+    """
+    if uf2:
+        return "uf2"
+    port = (variant.get("port") or port_for_family(str(variant.get("family") or ""))).lower()
+    if port in ("rp2", "samd"):
+        return "uf2"
+    return "bin"
+
+
+def _select_download(items: list[dict[str, str]], *, kind: str) -> Optional[dict[str, str]]:
+    """Prefer ``kind`` (bin/uf2); fall back to the first entry if none match."""
+    if not items:
+        return None
+    for item in items:
+        if artifact_kind(item.get("url") or "") == kind:
+            return item
+    return items[0]
+
+
 def pick_download(
     variant: dict[str, Any],
     *,
     version: Optional[str] = None,
     preview: bool = False,
     mp_variant: str = "",
     fetch: Optional[Fetcher] = None,
+    uf2: bool = False,
 ) -> dict[str, str]:
-    """Choose a download entry for board + MP variant (e.g. C6_WIFI)."""
+    """Choose a download entry for board + MP variant (e.g. C6_WIFI).
+
+    When both ``.bin`` and ``.uf2`` exist for the same version, prefer the
+    format the flasher will use (``.bin`` for esp32/esptool, ``.uf2`` for
+    rp2/samd). Pass ``uf2=True`` to force a UF2 (tinyuf2 on ESP32-S3, etc.).
+    """
     by_var = enrich_downloads_from_page(variant, fetch=fetch)
     mp_variant = mp_variant or ""
     if mp_variant not in by_var:
@@ -428,35 +468,46 @@ def pick_download(
             f"{variant.get('board')}; have: {known}"
         )
     downloads = by_var[mp_variant]
+    kind = preferred_artifact_kind(variant, uf2=uf2)
+    board = variant.get("board")
+    extra = f" / {mp_variant}" if mp_variant else ""
+
     if preview:
-        for d in downloads:
-            if d["channel"] == "preview":
-                return d
-        # Fall back to Thonny regex tweak filtered by variant name in URL.
+        chosen = _select_download(
+            [d for d in downloads if d["channel"] == "preview"], kind=kind
+        )
+        if chosen:
+            return chosen
         patched = maybe_latest_preview(
-            variant, fetch=fetch, mp_variant=mp_variant, by_variant=by_var
+            variant,
+            fetch=fetch,
+            mp_variant=mp_variant,
+            by_variant=by_var,
+            kind=kind,
         )
         if patched:
             return patched
-        raise RuntimeError(
-            f"no preview build for {variant.get('board')}"
-            + (f" / {mp_variant}" if mp_variant else "")
-        )
+        raise RuntimeError(f"no preview build for {board}{extra}")
+
     if version:
         ver = version.lstrip("v")
-        for d in downloads:
-            if d["version"].lstrip("v") == ver:
-                return d
-        raise RuntimeError(
-            f"version {version} not found for {variant.get('board')}"
-            + (f" / {mp_variant}" if mp_variant else "")
+        chosen = _select_download(
+            [d for d in downloads if d["version"].lstrip("v") == ver], kind=kind
         )
-    for d in downloads:
-        if d["channel"] == "release":
-            return d
+        if chosen:
+            return chosen
+        raise RuntimeError(f"version {version} not found for {board}{extra}")
+
+    chosen = _select_download(
+        [d for d in downloads if d["channel"] == "release"], kind=kind
+    )
+    if chosen:
+        return chosen
     if downloads:
-        return downloads[0]
-    raise RuntimeError(f"no downloads for {variant.get('board')}")
+        fallback = _select_download(downloads, kind=kind)
+        if fallback:
+            return fallback
+    raise RuntimeError(f"no downloads for {board}")
 
 
 def maybe_latest_preview(
@@ -465,13 +516,15 @@ def maybe_latest_preview(
     fetch: Optional[Fetcher] = None,
     mp_variant: str = "",
     by_variant: Optional[dict[str, list[dict[str, str]]]] = None,
+    kind: str = "",
 ) -> Optional[dict[str, str]]:
     """Pick latest preview for an MP variant from scraped page data."""
     if by_variant is None:
         by_variant = enrich_downloads_from_page(variant, fetch=fetch)
-    for d in by_variant.get(mp_variant or "", []):
-        if d["channel"] == "preview":
-            return d
+    previews = [d for d in by_variant.get(mp_variant or "", []) if d["channel"] == "preview"]
+    chosen = _select_download(previews, kind=kind) if kind else (previews[0] if previews else None)
+    if chosen:
+        return chosen
     # Thonny regex fallback (base image only).
     regex_s = variant.get("latest_prerelease_regex")
     info_url = variant.get("info_url") or ""
@@ -501,6 +554,8 @@ def maybe_latest_preview(
         m = rx.search(name)
         if not m:
             continue
+        if kind and artifact_kind(rel) and artifact_kind(rel) != kind:
+            continue
         ver_m = re.search(r"(v?\d+\.\d+\.\d+-preview\.\d+\.[a-z0-9]+)", name, re.I)
         version = ver_m.group(1) if ver_m else m.group(0)
         return {
@@ -554,6 +609,7 @@ def download_board(
     version: Optional[str] = None,
     preview: bool = False,
     mp_variant: str = "",
+    uf2: bool = False,
     data_prefix: str = DEFAULT_DATA_PREFIX,
     fetch: Optional[Fetcher] = None,
     catalog: Optional[list[dict[str, Any]]] = None,
@@ -568,6 +624,7 @@ def download_board(
         preview=preview,
         mp_variant=mp_variant or "",
         fetch=fetch,
+        uf2=uf2,
     )
     path = download_file(chosen["url"])
     st = path.stat()

cli/src/mpftp/sidecar.py

@@ -58,19 +58,37 @@ def _replace_remote_basename(remote_path: str, new_name: str) -> str:
     return new_name
 
 
+_ELF_MAGIC = b"\x7fELF"
+
+
+def _mpy_cross_runnable(path: Path) -> bool:
+    """True if this process can execute ``path`` (skip Linux ELF under Windows)."""
+    if not path.is_file():
+        return False
+    if sys.platform == "win32":
+        try:
+            with open(path, "rb") as f:
+                magic = f.read(4)
+        except OSError:
+            return False
+        if magic == _ELF_MAGIC:
+            return False
+    return True
+
+
 def find_mpy_cross(micropython_hint: Optional[str] = None, workspace: Optional[str] = None) -> str:
-    """Resolve mpy-cross: firmware-workspace build -> PATH -> a clear error."""
+    """Resolve mpy-cross, then mpy-cross.exe: firmware-workspace build -> PATH."""
     from .firmware import find_micropython
 
     mp = find_micropython(micropython_hint, workspace)
-    if mp is not None:
-        for name in ("mpy-cross", "mpy-cross.exe"):
+    for name in ("mpy-cross", "mpy-cross.exe"):
+        if mp is not None:
             candidate = mp / "mpy-cross" / "build" / name
-            if candidate.is_file():
+            if _mpy_cross_runnable(candidate):
                 return str(candidate)
-    found = shutil.which("mpy-cross")
-    if found:
-        return found
+        found = shutil.which(name)
+        if found and _mpy_cross_runnable(Path(found)):
+            return found
     raise RuntimeError(
         "mpy-cross not found. Build it in your MicroPython tree (make -C mpy-cross), "
         "`pip install mpy-cross`, or point mpftp.workspacePath / mpftp.micropythonPath "
@@ -2689,10 +2707,15 @@ def romfs_build(
         self._require_micropython("romfs")
         from mpremote import commands as mp_cmd
 
+        # Host-only: mpremote still calls state.did_action() before make_romfs.
+        class _HostState:
+            def did_action(self):
+                pass
+
         args = argparse.Namespace(path=path, output=output, mpy=mpy)
         buf = io.StringIO()
         with contextlib.redirect_stdout(buf):
-            mp_cmd._do_romfs_build(None, args)
+            mp_cmd._do_romfs_build(_HostState(), args)
         out_file = output or (path + ".romfs")
         size = Path(out_file).stat().st_size if Path(out_file).is_file() else 0
         return {"output": buf.getvalue().strip(), "output_file": out_file, "size": size}