simantic 0.2.0__py3-none-any.whl

simantic/install.py

@@ -0,0 +1,313 @@
+"""Fetching simulator binaries.
+
+Reads the same release manifest the CLIs self-update from, so a binary
+installed here is the same artifact `sim update` would have produced:
+
+    releases/<product>/<channel>.json
+    {"version": "0.4.0",
+     "artifacts": {"osx-arm64": {"url": ..., "sha256": ...}, ...}}
+
+The channel is just the manifest name, so publishing a pre-release means
+uploading a second pointer beside latest.json rather than standing up
+anything new.
+
+Binaries land in ~/.simantic/bin, which the resolver searches. Nothing is
+written into site-packages: an installed package may be read-only, and a
+binary there would vanish on the next upgrade.
+
+Releases are public objects, keyed by version, so fetching needs no account;
+checksums from the manifest are what make a download trustworthy.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import io
+import json
+import os
+import shutil
+import platform
+import stat
+import tarfile
+import urllib.error
+import urllib.parse
+import urllib.request
+import zipfile
+from dataclasses import dataclass
+from pathlib import Path
+
+
+RELEASES_URL = "https://drjdhqfvrttolueolzif.supabase.co/storage/v1/object/public/releases"
+
+
+def releases_url() -> str:
+    """Where manifests are served from. $SIMANTIC_RELEASES_URL overrides.
+
+    Overridable so a release can be rehearsed against a staging host (or a
+    plain directory served over HTTP) before it is published.
+    """
+    return os.environ.get("SIMANTIC_RELEASES_URL", RELEASES_URL).rstrip("/")
+
+
+#: The manifest to read. $SIMANTIC_CHANNEL selects a pre-release channel.
+DEFAULT_CHANNEL = "latest"
+
+
+def default_channel() -> str:
+    return os.environ.get("SIMANTIC_CHANNEL") or DEFAULT_CHANNEL
+
+
+class InstallError(RuntimeError):
+    """The binary could not be fetched or verified."""
+
+
+@dataclass(frozen=True)
+class Artifact:
+    version: str
+    url: str
+    sha256: str | None
+
+
+def simantic_home() -> Path:
+    """Where managed binaries live. $SIMANTIC_HOME overrides."""
+    configured = os.environ.get("SIMANTIC_HOME")
+    if configured:
+        return Path(configured)
+    home = os.environ.get("HOME")
+    if not home:
+        raise InstallError("$HOME is not set; set $SIMANTIC_HOME instead")
+    return Path(home) / ".simantic"
+
+
+def bin_dir() -> Path:
+    return simantic_home() / "bin"
+
+
+def current_rid() -> str:
+    """The release-manifest key for this machine.
+
+    Mirrors the .NET runtime identifiers the release workflow publishes under,
+    so both installers read the same manifest keys.
+    """
+    machine = platform.machine().lower()
+    arch = {
+        "x86_64": "x64", "amd64": "x64",
+        "arm64": "arm64", "aarch64": "arm64",
+    }.get(machine)
+    system = {"darwin": "osx", "linux": "linux", "windows": "win"}.get(
+        platform.system().lower()
+    )
+    if not arch or not system:
+        raise InstallError(
+            f"unsupported platform: {platform.system()} {platform.machine()}"
+        )
+    return f"{system}-{arch}"
+
+
+#: Binary name -> release product prefix. A product that has published no
+#: manifest yet fails with a clear message rather than a stray 404.
+PRODUCTS = {
+    "sim": "cli",
+    "analog-cli": "analog",
+    "pyrite": "pyrite",
+    "pyrite-mcp": "pyrite",
+}
+
+
+def fetch_manifest(
+    binary: str, *, channel: str | None = None, timeout: float = 30
+) -> dict:
+    product = PRODUCTS.get(binary)
+    if product is None:
+        raise InstallError(
+            f"unknown binary {binary!r}; expected one of {sorted(PRODUCTS)}"
+        )
+    channel = channel or default_channel()
+    request = urllib.request.Request(f"{releases_url()}/{product}/{channel}.json")
+    try:
+        with urllib.request.urlopen(request, timeout=timeout) as response:
+            return json.loads(response.read())
+    except urllib.error.HTTPError as exc:
+        raise InstallError(
+            f"no published releases for {binary!r} (HTTP {exc.code} from {url}). "
+            "Install the binary yourself and point $SIMANTIC_* at it."
+        ) from None
+    except urllib.error.URLError as exc:
+        raise InstallError(f"cannot reach the release server: {exc.reason}") from None
+    except json.JSONDecodeError as exc:
+        raise InstallError(f"release manifest is not valid JSON: {exc}") from None
+
+
+def resolve(
+    binary: str, *, rid: str | None = None, channel: str | None = None
+) -> Artifact:
+    """The artifact this machine should download."""
+    manifest = fetch_manifest(binary, channel=channel)
+    version = manifest.get("version")
+    artifacts = manifest.get("artifacts")
+    if not version or not isinstance(artifacts, dict):
+        raise InstallError("release manifest is missing version or artifacts")
+
+    rid = rid or current_rid()
+    entry = artifacts.get(rid)
+    if not entry or not entry.get("url"):
+        available = ", ".join(sorted(artifacts)) or "none"
+        raise InstallError(
+            f"no {rid} build in {binary} release {version} (available: {available})"
+        )
+    return Artifact(version=version, url=entry["url"], sha256=entry.get("sha256"))
+
+
+def download(artifact: Artifact, *, timeout: float = 300) -> bytes:
+    """Fetch the artifact and verify its checksum before it is trusted."""
+    request = urllib.request.Request(artifact.url)
+    try:
+        with urllib.request.urlopen(request, timeout=timeout) as response:
+            payload = response.read()
+    except urllib.error.HTTPError as exc:
+        raise InstallError(f"download failed: HTTP {exc.code}") from None
+    except urllib.error.URLError as exc:
+        raise InstallError(f"download failed: {exc.reason}") from None
+
+    if artifact.sha256:
+        actual = hashlib.sha256(payload).hexdigest()
+        if actual.lower() != artifact.sha256.strip().lower():
+            raise InstallError(
+                f"checksum mismatch (expected {artifact.sha256}, got {actual}). "
+                "Refusing to install."
+            )
+    return payload
+
+
+def _extract(payload: bytes, binary: str) -> bytes:
+    """The executable inside a release archive, or the payload if it is raw.
+
+    Both archive formats the release workflows produce are handled: zip and
+    gzipped tar. Anything else is passed through, because older manifests
+    pointed straight at the executable.
+    """
+    if payload.startswith(b"PK\x03\x04"):
+        with zipfile.ZipFile(io.BytesIO(payload)) as archive:
+            names = [n for n in archive.namelist() if not n.endswith("/")]
+            return _pick(names, binary, archive.read)
+    if payload.startswith(b"\x1f\x8b"):
+        with tarfile.open(fileobj=io.BytesIO(payload), mode="r:gz") as archive:
+            names = [m.name for m in archive.getmembers() if m.isfile()]
+
+            def read(name: str) -> bytes:
+                handle = archive.extractfile(name)
+                if handle is None:  # pragma: no cover - filtered to files above
+                    raise InstallError(f"cannot read {name!r} from the archive")
+                return handle.read()
+
+            return _pick(names, binary, read)
+    return payload
+
+
+def _pick(names: list[str], binary: str, read) -> bytes:
+    """The entry that is the executable, by name or by being the only one."""
+    for name in names:
+        # Release archives sometimes nest the binary under a directory.
+        if name == binary or name.endswith(f"/{binary}"):
+            return read(name)
+    if len(names) == 1:
+        return read(names[0])
+    raise InstallError(
+        f"release archive has no {binary!r} entry (contains: {', '.join(names)})"
+    )
+
+
+def install(binary: str, *, force: bool = False, channel: str | None = None) -> Path:
+    """Download `binary` into the managed bin directory; return its path."""
+    target = bin_dir() / binary
+    if target.exists() and not force:
+        return target
+
+    artifact = resolve(binary, channel=channel)
+    executable = _extract(download(artifact), binary)
+
+    target.parent.mkdir(parents=True, exist_ok=True)
+    # Stage beside the target so the rename is atomic on the same filesystem,
+    # and a partial download can never be left looking like a usable binary.
+    tmp = target.with_name(f".{binary}.incoming")
+    try:
+        tmp.write_bytes(executable)
+        tmp.chmod(tmp.stat().st_mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)
+        os.replace(tmp, target)
+    except OSError as exc:
+        tmp.unlink(missing_ok=True)
+        raise InstallError(f"cannot write {target}: {exc}") from None
+    return target
+
+
+# -- the engine: Simantic.Core + a private .NET runtime, for in-process use ----
+
+ENGINE_KEY = "engine"
+
+
+def engine_root() -> Path:
+    """Where engine releases live: ~/.simantic/engine/<version>/."""
+    return simantic_home() / "engine"
+
+
+def installed_engine() -> Path | None:
+    """The newest installed engine directory, or None."""
+    root = engine_root()
+    if not root.exists():
+        return None
+    candidates = [
+        d for d in root.iterdir()
+        if (d / "Simantic.Core.dll").exists() and (d / "sim.runtimeconfig.json").exists()
+    ]
+    if not candidates:
+        return None
+    return max(candidates, key=lambda d: _version_key(d.name))
+
+
+def _version_key(name: str) -> tuple:
+    parts = []
+    for piece in name.replace("-", ".").split("."):
+        parts.append((0, int(piece)) if piece.isdigit() else (1, piece))
+    return tuple(parts)
+
+
+def install_engine(*, force: bool = False, channel: str | None = None) -> Path:
+    """Download the engine for this machine into engine_root()/<version>.
+
+    One zip from the `sim` release manifest, key `engine-<rid>`: the
+    Simantic.Core publish directory plus a private .NET runtime under
+    `dotnet/`, laid out exactly as published.
+    """
+    artifact = resolve("sim", rid=f"{ENGINE_KEY}-{current_rid()}", channel=channel)
+    target = engine_root() / artifact.version
+    if (target / "Simantic.Core.dll").exists() and not force:
+        return target
+
+    payload = download(artifact)
+    if not payload.startswith(b"PK\x03\x04"):
+        raise InstallError("engine artifact is not a zip archive")
+    incoming = target.with_name(f".{artifact.version}.incoming")
+    if incoming.exists():
+        shutil.rmtree(incoming)
+    incoming.mkdir(parents=True)
+    try:
+        with zipfile.ZipFile(io.BytesIO(payload)) as archive:
+            for name in archive.namelist():
+                # Refuse anything that would land outside the target.
+                dest = (incoming / name).resolve()
+                if not str(dest).startswith(str(incoming.resolve())):
+                    raise InstallError(f"engine archive has an unsafe path: {name}")
+            archive.extractall(incoming)
+        if target.exists():
+            shutil.rmtree(target)
+        os.replace(incoming, target)
+    except (OSError, zipfile.BadZipFile) as exc:
+        shutil.rmtree(incoming, ignore_errors=True)
+        raise InstallError(f"cannot unpack the engine into {target}: {exc}") from None
+    return target
+
+
+def installed_version(binary: str) -> str | None:
+    """Nothing is recorded locally, so this reports presence, not version."""
+    target = bin_dir() / binary
+    return str(target) if target.exists() else None

simantic/mcu.py

@@ -0,0 +1,163 @@
+"""Driving the `sim` binary — firmware simulation.
+
+Platforms come from one of two places. `mcu=` names a model, which `sim`
+resolves for you and which requires authentication (`sim auth`); models are
+not distributed with this package. `repl=` points at a platform file you
+supply yourself.
+
+`sim` emits no structured report: the only observable is UART text, written
+to --output. The verdict therefore comes from substring matching, which is
+the contract `test.yaml` manifests use (`expect` / `expect_absent`) and the
+reason test firmware conventionally prints a `RESULT: PASS` marker.
+
+Some installations require a separate simulation server. This module does
+not assume either way — it reads that from what the binary reports, so the
+same code drives both.
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import tempfile
+from collections.abc import Sequence
+from dataclasses import dataclass
+from pathlib import Path
+
+from ._locate import locate
+from . import telemetry
+
+ENV_VAR = "SIMANTIC_SIM"
+BINARY = "sim"
+
+#: Values accepted by `sim --backend`. Which are available, and which targets
+#: each supports, depends on the installed build — see its --help.
+BACKENDS = ("tlib", "rust")
+
+
+class SimError(RuntimeError):
+    """The simulator could not run: a bad platform, a missing ELF, a failed start."""
+
+
+class ServerNotConfigured(SimError):
+    """This installation needs a simulation server and none was given.
+
+    Separate from SimError because it is an unconfigured environment, not a
+    simulation result: a test runner should skip on it, the way it skips on
+    a missing binary, rather than report a firmware failure.
+    """
+
+
+@dataclass(frozen=True)
+class SimRun:
+    """One firmware run: the UART transcript plus the verdict against it."""
+
+    output: str
+    exit_code: int
+    missing: list[str]
+    forbidden: list[str]
+    #: Which binary produced this, so a failure names the thing that ran.
+    runner: str = "sim"
+
+    @property
+    def passed(self) -> bool:
+        return self.exit_code == 0 and not self.missing and not self.forbidden
+
+    def failure_report(self) -> str:
+        lines = []
+        if self.exit_code != 0:
+            lines.append(f"{self.runner} exited {self.exit_code}")
+        for text in self.missing:
+            lines.append(f"  expected but not found: {text!r}")
+        for text in self.forbidden:
+            lines.append(f"  present but forbidden: {text!r}")
+        transcript = self.output.strip() or "(no UART output)"
+        lines.append("--- UART ---")
+        lines.append(transcript)
+        return "\n".join(lines)
+
+
+def sim_binary(explicit: str | os.PathLike[str] | None = None) -> Path:
+    """Resolve the sim binary, or raise BinaryNotFound."""
+    return locate(BINARY, ENV_VAR, explicit)
+
+
+def run(
+    elf: str | os.PathLike[str],
+    *,
+    repl: str | os.PathLike[str] | None = None,
+    mcu: str | None = None,
+    server: str | None = None,
+    timeout: int = 15,
+    expect: Sequence[str] = (),
+    expect_absent: Sequence[str] = (),
+    backend: str | None = None,
+    use_cached: bool = False,
+    ascii_output: bool = True,
+    only_messages: bool = True,
+    binary: str | os.PathLike[str] | None = None,
+) -> SimRun:
+    """Run one firmware ELF and check its UART against expectations.
+
+    Give exactly one of `mcu` (a backend-resolved model, needs auth) or
+    `repl` (a local platform file). `server` defaults to $SIM_SERVER_URL,
+    which `sim` itself reads — it is passed explicitly only when given here.
+
+    `use_cached` reuses a previously fetched model from ~/.sim_cache, which
+    keeps a suite runnable without a round trip per test.
+
+    Defaults mirror what a fixture wants to read: ASCII rather than hex, and
+    message text without the `[t] (LABEL)` prefix.
+    """
+    if (repl is None) == (mcu is None):
+        raise ValueError("give exactly one of repl= or mcu=")
+    if backend is not None and backend not in BACKENDS:
+        raise ValueError(f"backend must be one of {BACKENDS}, got {backend!r}")
+    telemetry.record("sdk.run_firmware")
+    with tempfile.TemporaryDirectory() as tmp:
+        out_path = Path(tmp) / "uart.txt"
+        cmd = [
+            str(sim_binary(binary)),
+            "--elf", str(elf),
+            "--timeout", str(timeout),
+            "--output", str(out_path),
+        ]
+        cmd += ["--repl", str(repl)] if repl is not None else ["--mcu", mcu]
+        if server is not None:
+            cmd += ["--server", server]
+        if use_cached:
+            cmd.append("--use-cached")
+        if ascii_output:
+            cmd.append("--ascii")
+        if only_messages:
+            cmd.append("--only-messages")
+        if backend is not None:
+            cmd += ["--backend", backend]
+
+        # Give the subprocess room past the simulated timeout before treating
+        # it as hung: --timeout bounds simulated time, not wall-clock.
+        try:
+            proc = subprocess.run(
+                cmd, capture_output=True, text=True, timeout=timeout * 4 + 30
+            )
+        except subprocess.TimeoutExpired as exc:
+            raise SimError(f"sim did not exit within its wall-clock budget: {exc}") from None
+
+        output = out_path.read_text(errors="replace") if out_path.exists() else ""
+
+    if proc.returncode != 0 and not output:
+        stderr = proc.stderr.strip()
+        # Matched against what sim reports rather than pre-checked: whether a
+        # server is needed depends on the installation, not on this package.
+        if "sim-server" in stderr:
+            raise ServerNotConfigured(
+                f"{stderr}\nPass server= or set $SIM_SERVER_URL."
+            )
+        raise SimError(f"sim exited {proc.returncode} with no output\n{stderr}")
+
+    return SimRun(
+        output=output,
+        exit_code=proc.returncode,
+        missing=[t for t in expect if t not in output],
+        forbidden=[t for t in expect_absent if t in output],
+    )

simantic/pyrite.py

@@ -0,0 +1,72 @@
+"""Driving the `pyrite` binary — offline Cortex-M firmware runs.
+
+A single self-contained binary: it loads an ELF, runs it for a budget of
+virtual time, and writes the UART transcript to stdout. Nothing else has to
+be installed or started.
+
+The platform is either a bundled board (`board=`) or an mcu-lib `.repl` file
+you supply (`repl=`). Like the other runner, the verdict is substring
+matching over the transcript, because UART text is the only observable.
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+from collections.abc import Sequence
+from pathlib import Path
+
+from ._locate import locate
+from .mcu import SimError, SimRun
+from . import telemetry
+
+ENV_VAR = "SIMANTIC_PYRITE"
+BINARY = "pyrite"
+
+
+def pyrite_binary(explicit: str | os.PathLike[str] | None = None) -> Path:
+    """Resolve the pyrite binary, or raise BinaryNotFound."""
+    return locate(BINARY, ENV_VAR, explicit)
+
+
+def run(
+    elf: str | os.PathLike[str],
+    *,
+    board: str | None = None,
+    repl: str | os.PathLike[str] | None = None,
+    timeout: int = 5,
+    expect: Sequence[str] = (),
+    expect_absent: Sequence[str] = (),
+    binary: str | os.PathLike[str] | None = None,
+) -> SimRun:
+    """Run one firmware ELF and check its UART against expectations.
+
+    Give exactly one of `board` (bundled) or `repl` (a platform file).
+    `timeout` is a budget of simulated time, not wall-clock.
+    """
+    if (board is None) == (repl is None):
+        raise ValueError("give exactly one of board= or repl=")
+
+    telemetry.record("sdk.run_pyrite")
+    cmd = [str(pyrite_binary(binary)), "run", "--elf", str(elf), "--timeout", str(timeout)]
+    cmd += ["--board", board] if board is not None else ["--repl", str(repl)]
+
+    # Wall-clock room beyond the virtual-time budget before calling it hung.
+    try:
+        proc = subprocess.run(
+            cmd, capture_output=True, text=True, timeout=timeout * 4 + 30
+        )
+    except subprocess.TimeoutExpired as exc:
+        raise SimError(f"pyrite did not exit within its wall-clock budget: {exc}") from None
+
+    output = proc.stdout
+    if proc.returncode != 0 and not output.strip():
+        raise SimError(f"pyrite exited {proc.returncode}\n{proc.stderr.strip()}")
+
+    return SimRun(
+        output=output,
+        exit_code=proc.returncode,
+        missing=[t for t in expect if t not in output],
+        forbidden=[t for t in expect_absent if t in output],
+        runner="pyrite",
+    )