Barmaja-PyArduino 2.0.0__py3-none-any.whl

Barmaja_PyArduino/environment.py

@@ -0,0 +1,595 @@
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import platform
+import shutil
+import subprocess
+import sys
+import tempfile
+from dataclasses import dataclass, asdict
+from pathlib import Path
+from typing import Iterable
+
+CACHE_SCHEMA = 2
+
+
+def _home() -> Path:
+    override = os.environ.get("BARMAJA_HOME")
+    if override:
+        return Path(override).expanduser().resolve()
+    base = Path(os.environ.get("LOCALAPPDATA") or os.environ.get("APPDATA") or Path.home())
+    return (base / "BarmajaPyArduino").resolve()
+
+
+def ascii_runtime_root() -> Path:
+    override = os.environ.get("BARMAJA_RUNTIME_ROOT")
+    if override:
+        return Path(override).expanduser().resolve()
+    if os.name == "nt":
+        drive = os.environ.get("SystemDrive", "C:")
+        return Path(drive + "\\BarmajaPyArduino")
+    return Path(tempfile.gettempdir()) / "barmaja-pyarduino"
+
+
+def ensure_runtime_dirs() -> dict[str, Path]:
+    root = ascii_runtime_root()
+    dirs = {
+        "root": root,
+        "data": root / "arduino-data",
+        "user": root / "arduino-user",
+        "downloads": root / "downloads",
+        "build": root / "build",
+        "cache": _home() / "cache",
+    }
+    for p in dirs.values():
+        p.mkdir(parents=True, exist_ok=True)
+    return dirs
+
+
+def private_arduino_library_roots() -> tuple[Path, ...]:
+    """Existing BARMAJA private Arduino library roots, in priority order.
+
+    Restored in 1.1.0.dev7: ``live.py`` (LiveRun firmware install) imports this
+    function, but it was missing from the 0.7.0.dev1 "student-errors" build and
+    every V1.1 dev build, so ``upload()`` followed by ``LiveRun()`` failed with
+    ImportError.  Installed packs use ``arduino-libraries``; portable/source
+    packs use ``arduino_libraries``.  Both are accepted.
+    """
+    root = ensure_runtime_dirs()["root"]
+    found: list[Path] = []
+    seen: set[str] = set()
+    for candidate in (root / "arduino-libraries", root / "arduino_libraries"):
+        if not candidate.is_dir():
+            continue
+        try:
+            resolved = Path(os.path.abspath(os.fspath(candidate))) if os.name == "nt" else candidate.resolve()
+        except OSError:
+            resolved = candidate
+        key = os.path.normcase(str(resolved))
+        if key not in seen:
+            found.append(resolved)
+            seen.add(key)
+    return tuple(found)
+
+
+def package_version() -> str:
+    # The package's own version is authoritative: PictoBlox copies have no
+    # dist-info, and a stale dist-info must never mask the code actually loaded.
+    from . import __version__
+    return __version__
+
+
+def arduino_cli_environment(executable: str | Path | None = None) -> dict[str, str]:
+    """Environment for every Arduino CLI call Barmaja makes.
+
+    - English output, so memory reports and error translation are stable on
+      Arabic/French/... Windows installations;
+    - no network update notification (offline classrooms);
+    - an ASCII-only build cache (non-ASCII Windows user names break some AVR tools);
+    - when the pinned Full-Pack CLI is used, ignore inherited ``ARDUINO_*``
+      variables so another Arduino/ESP32 installation cannot redirect Barmaja
+      away from its tested offline runtime.
+
+    Only Barmaja's own subprocesses see these values; the user's Arduino IDE
+    configuration files and machine/user environment variables are never modified.
+    """
+    env = dict(os.environ)
+
+    # The Full Offline runtime must be isolated from machine/user Arduino
+    # overrides.  External/Light-Pack Arduino CLI installations keep their
+    # normal environment so Barmaja does not interfere with a user's IDE setup.
+    bundled = False
+    if executable:
+        try:
+            exe = Path(str(executable)).expanduser().resolve()
+            runtime = (ascii_runtime_root() / "runtime").resolve()
+            bundled = exe.parent == runtime and exe.name.lower() in {"arduino-cli", "arduino-cli.exe"}
+        except OSError:
+            bundled = False
+    if bundled:
+        for key in tuple(env):
+            if key.upper().startswith("ARDUINO_"):
+                env.pop(key, None)
+
+    env["ARDUINO_LOCALE"] = "en"
+    env["ARDUINO_UPDATER_ENABLE_NOTIFICATION"] = "false"
+    env["ARDUINO_METRICS_ENABLED"] = "false"
+    try:
+        cache = ascii_runtime_root() / "build-cache"
+        cache.mkdir(parents=True, exist_ok=True)
+        env["ARDUINO_BUILD_CACHE_PATH"] = str(cache)
+    except OSError:
+        pass
+    return env
+
+
+def _kill_process_tree(proc: subprocess.Popen) -> None:
+    try:
+        if os.name == "nt":
+            subprocess.run(
+                ["taskkill", "/F", "/T", "/PID", str(proc.pid)],
+                capture_output=True, check=False, timeout=15,
+                creationflags=getattr(subprocess, "CREATE_NO_WINDOW", 0),
+            )
+        else:
+            import signal
+            os.killpg(proc.pid, signal.SIGKILL)
+    except Exception:
+        pass
+    try:
+        proc.kill()
+    except Exception:
+        pass
+
+
+def run_text(args: list[str], *, timeout: float = 20.0, cwd: str | Path | None = None) -> subprocess.CompletedProcess[str]:
+    """Run an external tool with UTF-8 capture and a hard timeout.
+
+    On timeout the whole process tree (arduino-cli -> avr-gcc/avrdude) is
+    terminated so no orphaned compiler keeps build files or the COM port locked.
+    """
+    from .errors import ToolchainError
+    kwargs: dict = dict(
+        cwd=str(cwd) if cwd else None,
+        stdout=subprocess.PIPE, stderr=subprocess.PIPE, stdin=subprocess.DEVNULL,
+        text=True, encoding="utf-8", errors="replace",
+        env=arduino_cli_environment(args[0] if args else None),
+    )
+    if os.name == "nt":
+        # No console windows flashing when called from PictoBlox/IDE GUIs.
+        kwargs["creationflags"] = getattr(subprocess, "CREATE_NEW_PROCESS_GROUP", 0) | getattr(subprocess, "CREATE_NO_WINDOW", 0)
+    else:
+        kwargs["start_new_session"] = True
+    try:
+        proc = subprocess.Popen(args, **kwargs)
+    except OSError as e:
+        raise ToolchainError(f"Could not start {Path(str(args[0])).name}: {e.strerror or e}") from e
+    try:
+        out, err = proc.communicate(timeout=timeout)
+    except subprocess.TimeoutExpired as e:
+        _kill_process_tree(proc)
+        try:
+            proc.communicate(timeout=5)
+        except Exception:
+            pass
+        raise ToolchainError(f"External tool timed out after {timeout:g} seconds.") from e
+    return subprocess.CompletedProcess(args, proc.returncode, out or "", err or "")
+
+
+def env_seconds(name: str, default: float) -> float:
+    """Read a timeout override without crashing on a malformed value."""
+    raw = os.environ.get(name)
+    if not raw:
+        return default
+    try:
+        value = float(raw)
+    except ValueError:
+        return default
+    return value if value > 0 else default
+
+
+@dataclass(frozen=True)
+class EnvironmentFingerprint:
+    python_executable: str
+    python_version: str
+    platform: str
+    package_version: str
+    arduino_cli: str | None
+    arduino_cli_mtime_ns: int | None
+    avr_core_marker: str | None
+    library_markers: tuple[str, ...]
+    integrity_markers: tuple[str, ...] = ()
+
+    def digest(self) -> str:
+        payload = json.dumps(asdict(self), sort_keys=True, separators=(",", ":"), ensure_ascii=True)
+        return hashlib.sha256(payload.encode("utf-8")).hexdigest()
+
+
+def _marker(path: Path | None) -> str | None:
+    if not path or not path.exists():
+        return None
+    try:
+        st = path.stat()
+        return f"{path.resolve()}|{st.st_size}|{st.st_mtime_ns}"
+    except OSError:
+        return str(path)
+
+
+def _sha256_file(path: Path) -> str:
+    h = hashlib.sha256()
+    with path.open("rb") as f:
+        for chunk in iter(lambda: f.read(1024 * 1024), b""):
+            h.update(chunk)
+    return h.hexdigest()
+
+
+def _content_marker(path: Path | None, *, source_only: bool = False) -> str | None:
+    """Content-sensitive marker used only for cache safety.
+
+    A READY cache is allowed to skip the expensive test compile only for Barmaja's
+    pinned runtime.  For its core/libraries we hash compilation-relevant source and
+    metadata, and for tool ``bin`` directories we hash every file.  This deliberately
+    catches replacements that preserve file timestamps or sizes.
+    """
+    if not path or not path.exists():
+        return None
+    try:
+        path = path.resolve()
+        if path.is_file():
+            return f"sha256:{path}:{_sha256_file(path)}"
+        allowed = {".c", ".cc", ".cpp", ".cxx", ".h", ".hh", ".hpp", ".s", ".S", ".txt", ".properties", ".json", ".conf", ".cfg", ".yaml", ".yml"}
+        h = hashlib.sha256()
+        count = 0
+        for child in sorted((p for p in path.rglob("*") if p.is_file()), key=lambda p: str(p.relative_to(path)).lower()):
+            if source_only and child.suffix not in allowed and child.name not in {"platform.txt", "boards.txt", "programmers.txt"}:
+                continue
+            rel = child.relative_to(path).as_posix().encode("utf-8", "surrogatepass")
+            h.update(len(rel).to_bytes(4, "big")); h.update(rel)
+            h.update(bytes.fromhex(_sha256_file(child)))
+            count += 1
+        return f"tree-sha256:{path}:{count}:{h.hexdigest()}"
+    except OSError:
+        return None
+
+
+def _bundled_integrity_markers(cli_path: Path | None, libraries: Iterable[Path]) -> tuple[str, ...]:
+    """Strong markers for the immutable Full-Pack runtime; empty for other CLIs."""
+    if not cli_path or not cli_path.exists():
+        return ()
+    try:
+        runtime = (ensure_runtime_dirs()["root"] / "runtime").resolve()
+        cli_resolved = cli_path.resolve()
+        if cli_resolved.parent != runtime:
+            return ()
+    except OSError:
+        return ()
+
+    paths: list[tuple[Path, bool]] = [(cli_resolved, False)]
+    cfg = runtime / "arduino-cli.yaml"
+    if cfg.exists():
+        paths.append((cfg, False))
+
+    # Pinned AVR core source/configuration.
+    core_root = runtime / "arduino-data" / "packages" / "arduino" / "hardware" / "avr"
+    if core_root.exists():
+        for version_dir in sorted(p for p in core_root.iterdir() if p.is_dir()):
+            paths.append((version_dir, True))
+
+    # Compiler and upload executables. Hash the complete bin directories so a
+    # damaged helper (cc1plus/as/ld/objcopy/size/avrdude) cannot hide behind cache.
+    tools_root = runtime / "arduino-data" / "packages" / "arduino" / "tools"
+    if tools_root.exists():
+        for family in ("avr-gcc", "avrdude"):
+            fam = tools_root / family
+            if fam.exists():
+                for version_dir in sorted(p for p in fam.iterdir() if p.is_dir()):
+                    bin_dir = version_dir / "bin"
+                    paths.append((bin_dir if bin_dir.exists() else version_dir, False))
+
+    # Arduino CLI builtin discovery/monitor tools are required for fully-offline
+    # board detection/monitoring. Include them in the pinned-runtime fingerprint
+    # so quarantine/corruption cannot be hidden by a stale READY cache.
+    builtin_root = runtime / "arduino-data" / "packages" / "builtin" / "tools"
+    if builtin_root.exists():
+        for family in ("serial-discovery", "mdns-discovery", "dfu-discovery", "serial-monitor"):
+            fam = builtin_root / family
+            if fam.exists():
+                for version_dir in sorted(p for p in fam.iterdir() if p.is_dir()):
+                    paths.append((version_dir, False))
+
+    # Private libraries are authoritative because compile uses --library.  Hash
+    # their source trees, not merely library.properties.
+    roots: set[Path] = set()
+    for marker in libraries:
+        p = Path(marker)
+        root = p.parent if p.name == "library.properties" else p
+        try:
+            roots.add(root.resolve())
+        except OSError:
+            roots.add(root)
+    for root in sorted(roots, key=lambda p: str(p).lower()):
+        paths.append((root, True))
+
+    result=[]
+    for p, source_only in paths:
+        marker = _content_marker(p, source_only=source_only)
+        if marker:
+            result.append(marker)
+    return tuple(result)
+
+
+def make_fingerprint(arduino_cli: str | None, core_marker: Path | None = None, libraries: Iterable[Path] = ()) -> EnvironmentFingerprint:
+    cli_path = Path(arduino_cli) if arduino_cli else None
+    mtime = None
+    if cli_path and cli_path.exists():
+        try:
+            mtime = cli_path.stat().st_mtime_ns
+        except OSError:
+            pass
+    libs = tuple(libraries)
+    return EnvironmentFingerprint(
+        python_executable=str(Path(sys.executable).resolve()),
+        python_version=".".join(map(str, sys.version_info[:3])),
+        platform=f"{platform.system()}-{platform.machine()}",
+        package_version=package_version(),
+        arduino_cli=str(cli_path.resolve()) if cli_path and cli_path.exists() else arduino_cli,
+        arduino_cli_mtime_ns=mtime,
+        avr_core_marker=_marker(core_marker),
+        library_markers=tuple(sorted(filter(None, (_marker(p) for p in libs)))),
+        integrity_markers=_bundled_integrity_markers(cli_path, libs),
+    )
+
+
+def cache_file() -> Path:
+    p = ensure_runtime_dirs()["cache"] / "environment.json"
+    p.parent.mkdir(parents=True, exist_ok=True)
+    return p
+
+
+def load_cache() -> dict | None:
+    p = cache_file()
+    if not p.exists():
+        return None
+    try:
+        data = json.loads(p.read_text(encoding="utf-8"))
+        if data.get("schema") != CACHE_SCHEMA:
+            return None
+        return data
+    except Exception:
+        return None
+
+
+def save_cache(fingerprint: EnvironmentFingerprint, *, quick_fingerprint: EnvironmentFingerprint | None = None, status: str = "READY", source: str | None = None) -> None:
+    payload = {
+        "schema": CACHE_SCHEMA,
+        "status": status,
+        "fingerprint": fingerprint.digest(),
+        "quick_fingerprint": (quick_fingerprint or fingerprint).digest(),
+        "source": source,
+    }
+    p = cache_file()
+    tmp = p.with_suffix(".tmp")
+    tmp.write_text(json.dumps(payload, indent=2, sort_keys=True), encoding="utf-8")
+    tmp.replace(p)
+
+
+def invalidate_cache() -> None:
+    try:
+        cache_file().unlink(missing_ok=True)
+    except OSError:
+        pass
+
+
+def find_normal_arduino_cli() -> str | None:
+    override = os.environ.get("BARMAJA_ARDUINO_CLI")
+    if override and Path(override).exists():
+        return str(Path(override).resolve())
+    found = shutil.which("arduino-cli")
+    if found:
+        return found
+    candidates: list[Path] = []
+    if os.name == "nt":
+        ide_cli = Path("Arduino IDE") / "resources" / "app" / "lib" / "backend" / "resources" / "arduino-cli.exe"
+        local = os.environ.get("LOCALAPPDATA")
+        if local:
+            # Arduino IDE 2 "install for me only" (default) location.
+            candidates.append(Path(local) / "Programs" / ide_cli)
+        for env_name in ("LOCALAPPDATA", "PROGRAMFILES", "PROGRAMFILES(X86)"):
+            base = os.environ.get(env_name)
+            if base:
+                candidates.extend([
+                    Path(base) / ide_cli,
+                    Path(base) / "Arduino15" / "arduino-cli.exe",
+                ])
+    else:
+        candidates.extend([Path("/usr/bin/arduino-cli"), Path("/usr/local/bin/arduino-cli")])
+    for p in candidates:
+        if p.exists():
+            return str(p.resolve())
+    return None
+
+
+def pictoblox_root_candidates() -> tuple[Path, ...]:
+    roots: list[Path] = []
+    explicit = os.environ.get("BARMAJA_PICTOBLOX_ROOT")
+    if explicit:
+        p = Path(explicit).expanduser()
+        if p.exists(): roots.append(p.resolve())
+    if os.name == "nt":
+        for env_name in ("PROGRAMFILES", "PROGRAMFILES(X86)"):
+            base = os.environ.get(env_name)
+            if base:
+                p = Path(base) / "PictoBlox"
+                if p.exists(): roots.append(p.resolve())
+    unique=[]; seen=set()
+    for p in roots:
+        k=os.path.normcase(str(p))
+        if k not in seen: unique.append(p); seen.add(k)
+    return tuple(unique)
+
+
+def find_pictoblox_arduino_cli() -> str | None:
+    """Return a PictoBlox-bundled Arduino CLI only when an actual executable is found.
+
+    We intentionally do not infer compatibility from PictoBlox being installed. The
+    caller must still run version/core/library/capability checks before reuse.
+    """
+    explicit = os.environ.get("BARMAJA_PICTOBLOX_ARDUINO_CLI")
+    if explicit and Path(explicit).exists():
+        return str(Path(explicit).resolve())
+    rels = (
+        Path("resources") / "arduino-cli.exe",
+        Path("resources") / "app" / "arduino-cli.exe",
+        Path("resources") / "backend" / "arduino-cli.exe",
+        Path("resources") / "arduino" / "arduino-cli.exe",
+    )
+    for root in pictoblox_root_candidates():
+        for rel in rels:
+            p = root / rel
+            if p.exists(): return str(p.resolve())
+    return None
+
+
+def windows_documents_dir() -> Path | None:
+    """The real Documents folder (Known Folder API), including OneDrive/GPO redirection."""
+    if os.name != "nt":
+        return None
+    try:
+        import ctypes
+        import uuid
+        from ctypes import wintypes
+
+        class _GUID(ctypes.Structure):
+            _fields_ = [("Data1", wintypes.DWORD), ("Data2", wintypes.WORD), ("Data3", wintypes.WORD), ("Data4", ctypes.c_ubyte * 8)]
+
+        guid = _GUID()
+        ctypes.memmove(ctypes.byref(guid), uuid.UUID("{FDD39AD0-238F-46AF-ADB4-6C85480369C7}").bytes_le, 16)
+        out = ctypes.c_wchar_p()
+        hr = ctypes.windll.shell32.SHGetKnownFolderPath(ctypes.byref(guid), 0, None, ctypes.byref(out))
+        try:
+            if hr != 0 or not out.value:
+                return None
+            return Path(out.value)
+        finally:
+            ctypes.windll.ole32.CoTaskMemFree(out)
+    except Exception:
+        return None
+
+
+def other_windows_documents_candidates(users_root: str | Path | None = None) -> tuple[Path, ...]:
+    """Best-effort Documents locations for other local Windows user profiles.
+
+    This supplements the Known Folder API (current user only) for school PCs where
+    an administrator installs PictoBlox support for several student accounts.  We
+    only return directories that already exist; the caller still decides whether a
+    PictoBlox module target exists beneath them.
+    """
+    if users_root is None:
+        override = os.environ.get("BARMAJA_WINDOWS_USERS_ROOT")
+        if override:
+            users = Path(override)
+        else:
+            drive = os.environ.get("SystemDrive", "C:")
+            users = Path(drive + "\\Users")
+    else:
+        users = Path(users_root)
+    found: list[Path] = []
+    try:
+        profiles = [p for p in users.iterdir() if p.is_dir()]
+    except OSError:
+        return ()
+    for profile in profiles:
+        direct = profile / "Documents"
+        if direct.is_dir():
+            try: found.append(direct.resolve())
+            except OSError: found.append(direct)
+        try:
+            children = [p for p in profile.iterdir() if p.is_dir() and p.name.lower().startswith("onedrive")]
+        except OSError:
+            children = []
+        for cloud in children:
+            docs = cloud / "Documents"
+            if docs.is_dir():
+                try: found.append(docs.resolve())
+                except OSError: found.append(docs)
+    unique=[]; seen=set()
+    for p in found:
+        key=os.path.normcase(str(p))
+        if key not in seen:
+            unique.append(p); seen.add(key)
+    return tuple(unique)
+
+
+def documents_dir_candidates() -> tuple[Path, ...]:
+    candidates: list[Path] = []
+    known = windows_documents_dir()
+    if known:
+        candidates.append(known)
+    for env_name in ("OneDrive", "OneDriveConsumer", "OneDriveCommercial"):
+        base = os.environ.get(env_name)
+        if base:
+            candidates.append(Path(base) / "Documents")
+    userprofile = os.environ.get("USERPROFILE")
+    if userprofile:
+        candidates.append(Path(userprofile) / "Documents")
+    candidates.append(Path.home() / "Documents")
+    if os.name == "nt":
+        candidates.extend(other_windows_documents_candidates())
+    unique=[]; seen=set()
+    for p in candidates:
+        try: p=p.resolve()
+        except OSError: pass
+        key=os.path.normcase(str(p))
+        if key not in seen:
+            unique.append(p); seen.add(key)
+    return tuple(unique)
+
+
+def _running_pictoblox_modules_dir() -> Path | None:
+    """When imported from PictoBlox, the folder this package was loaded from."""
+    here = Path(__file__).resolve().parent.parent
+    return here if here.name.lower() == "python_modules" else None
+
+
+def pictoblox_module_dirs() -> tuple[Path, ...]:
+    found: list[Path] = []
+    override = os.environ.get("BARMAJA_PICTOBLOX_MODULES")
+    if override:
+        p = Path(override).expanduser()
+        # An explicit target is authoritative even before python_modules exists;
+        # the offline installer is responsible for creating it.
+        try: found.append(p.resolve())
+        except OSError: found.append(p)
+    running = _running_pictoblox_modules_dir()
+    if running is not None:
+        found.append(running)
+    for docs in documents_dir_candidates():
+        for name in ("Pictoblox", "PictoBlox"):
+            p = docs / name / "python_modules"
+            try:
+                # Existing python_modules is ideal; an existing PictoBlox folder
+                # is also enough for the offline installer to create python_modules.
+                if p.exists() or p.parent.exists():
+                    found.append(p.resolve())
+            except OSError:
+                continue
+    unique = []
+    seen = set()
+    for p in found:
+        key = os.path.normcase(str(p))
+        if key not in seen:
+            unique.append(p); seen.add(key)
+    return tuple(unique)
+
+
+def installed_package_version(package_dir: Path) -> str | None:
+    """Read __version__ from an installed Barmaja_PyArduino copy without importing it."""
+    import re
+    try:
+        text = (package_dir / "__init__.py").read_text(encoding="utf-8", errors="replace")
+    except OSError:
+        return None
+    m = re.search(r"^__version__\s*=\s*[\"']([^\"']+)[\"']", text, re.M)
+    return m.group(1) if m else None