simantic 0.2.0__py3-none-any.whl

simantic/auth.py

@@ -0,0 +1,221 @@
+"""Credentials for the Simantic backend.
+
+Reads and writes `~/.sim_id`, the same `EMAIL=`/`API_KEY=` file the CLIs use.
+Deliberately not a second credential store: authenticating here authenticates
+the CLIs too, and vice versa.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+import urllib.error
+import urllib.request
+import webbrowser
+from dataclasses import dataclass
+from pathlib import Path
+
+VALIDATE_URL = "https://drjdhqfvrttolueolzif.supabase.co/functions/v1/validate-token"
+LOGIN_START_URL = "https://drjdhqfvrttolueolzif.supabase.co/functions/v1/cli-login-start"
+LOGIN_POLL_URL = "https://drjdhqfvrttolueolzif.supabase.co/functions/v1/cli-login-poll"
+
+#: Personal access tokens carry this prefix; anything else is a paste error.
+TOKEN_PREFIX = "smtc_"
+
+
+class AuthError(RuntimeError):
+    """The token is malformed, rejected, or could not be stored."""
+
+
+class NotAuthenticated(AuthError):
+    """No credentials on this machine."""
+
+
+@dataclass(frozen=True)
+class Credentials:
+    email: str
+    api_key: str
+
+
+def sim_id_path() -> Path:
+    """`~/.sim_id`, honouring $HOME so tests can redirect it."""
+    home = os.environ.get("HOME")
+    if not home:
+        raise AuthError("$HOME is not set")
+    return Path(home) / ".sim_id"
+
+
+def load() -> Credentials:
+    """Read stored credentials, or raise NotAuthenticated."""
+    path = sim_id_path()
+    try:
+        text = path.read_text()
+    except OSError:
+        raise NotAuthenticated(
+            f"no credentials at {path} — run `simantic auth`"
+        ) from None
+
+    fields = {}
+    for line in text.splitlines():
+        key, sep, value = line.partition("=")
+        if sep:
+            fields[key.strip()] = value.strip()
+
+    api_key = fields.get("API_KEY")
+    if not api_key:
+        raise NotAuthenticated(f"{path} has no API_KEY — run `simantic auth`")
+    return Credentials(email=fields.get("EMAIL", ""), api_key=api_key)
+
+
+def check_token(token: str) -> None:
+    """Reject tokens that cannot be valid, before spending a round trip.
+
+    The ASCII check is not cosmetic: a token pasted with a non-breaking space
+    or newline would otherwise be smuggled into an Authorization header.
+    """
+    if not token:
+        raise AuthError("no token provided")
+    if not token.startswith(TOKEN_PREFIX):
+        raise AuthError(
+            f"not an {TOKEN_PREFIX} token — create one on the dashboard's "
+            "/account/api page"
+        )
+    if not all(0x21 <= ord(c) <= 0x7E for c in token):
+        raise AuthError(
+            "token contains whitespace or non-ASCII characters — re-copy it "
+            "from /account/api"
+        )
+
+
+def validate(token: str, *, timeout: float = 10) -> str:
+    """Ask the backend to accept the token; return the account's email."""
+    check_token(token)
+    request = urllib.request.Request(
+        os.environ.get("SIMANTIC_VALIDATE_URL", VALIDATE_URL),
+        data=b"",
+        method="POST",
+        headers={"Authorization": f"Bearer {token}"},
+    )
+    try:
+        with urllib.request.urlopen(request, timeout=timeout) as response:
+            body = response.read().decode(errors="replace")
+    except urllib.error.HTTPError as exc:
+        if exc.code == 401:
+            raise AuthError(
+                "token rejected by the backend — check it on the dashboard's "
+                "/account/api page"
+            ) from None
+        detail = exc.read().decode(errors="replace").strip()[:200]
+        raise AuthError(f"validate-token returned HTTP {exc.code}: {detail}") from None
+    except urllib.error.URLError as exc:
+        raise AuthError(f"cannot reach the simantic backend: {exc.reason}") from None
+
+    return _email_from(body)
+
+
+def _email_from(body: str) -> str:
+    """The email in a validate-token response, or "" if it carries none."""
+    try:
+        data = json.loads(body)
+    except json.JSONDecodeError:
+        return ""
+    if isinstance(data, dict):
+        for key in ("email", "user_email"):
+            value = data.get(key)
+            if isinstance(value, str):
+                return value
+    return ""
+
+
+def save(token: str, email: str) -> Path:
+    """Store credentials 0600, atomically.
+
+    Written to a temp file that is 0600 from birth and then renamed, so there
+    is no world-readable window and no truncate-in-place of a file the CLIs
+    may be reading concurrently.
+    """
+    path = sim_id_path()
+    tmp = path.with_suffix(".tmp")
+    try:
+        fd = os.open(tmp, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+        try:
+            os.write(fd, f"EMAIL={email}\nAPI_KEY={token}\n".encode())
+        finally:
+            os.close(fd)
+        os.replace(tmp, path)
+    except OSError as exc:
+        tmp.unlink(missing_ok=True)
+        raise AuthError(f"cannot write {path}: {exc}") from None
+    return path
+
+
+def login(token: str) -> Credentials:
+    """Validate a token and store it. The whole `simantic auth` flow."""
+    email = validate(token)
+    save(token, email)
+    return Credentials(email=email, api_key=token)
+
+
+def _post_json(url: str, body: dict, *, timeout: float) -> dict:
+    """POST a JSON body, return the JSON response. Shared by start and poll."""
+    request = urllib.request.Request(
+        url,
+        data=json.dumps(body).encode(),
+        method="POST",
+        headers={"Content-Type": "application/json"},
+    )
+    try:
+        with urllib.request.urlopen(request, timeout=timeout) as response:
+            return json.loads(response.read())
+    except urllib.error.HTTPError as exc:
+        detail = exc.read().decode(errors="replace").strip()[:200]
+        raise AuthError(f"{url} returned HTTP {exc.code}: {detail}") from None
+    except urllib.error.URLError as exc:
+        raise AuthError(f"cannot reach the simantic backend: {exc.reason}") from None
+    except json.JSONDecodeError as exc:
+        raise AuthError(f"{url} returned invalid JSON: {exc}") from None
+
+
+def browser_login(*, open_browser: bool = True, timeout: float = 600) -> Credentials:
+    """Authenticate via the device flow: a browser tab, not a pasted token.
+
+    Mirrors `gh auth login` — the code is printed so it is visible even when
+    the browser can't be opened (headless, SSH), and the URL is printed
+    unconditionally as the fallback for that case.
+    """
+    start_url = os.environ.get("SIMANTIC_CLI_LOGIN_START_URL", LOGIN_START_URL)
+    poll_url = os.environ.get("SIMANTIC_CLI_LOGIN_POLL_URL", LOGIN_POLL_URL)
+
+    start = _post_json(start_url, {}, timeout=10)
+    device_code = start.get("device_code")
+    user_code = start.get("user_code")
+    verify_url = start.get("verify_url")
+    interval = start.get("interval", 3)
+    if not device_code or not user_code or not verify_url:
+        raise AuthError(f"{start_url} returned an incomplete response")
+
+    print(f"First copy your one-time code: {user_code}")
+    print(f"Then open this URL in your browser to confirm: {verify_url}")
+    if open_browser:
+        try:
+            webbrowser.open(verify_url)
+        except Exception:
+            pass  # the URL above is already the fallback
+
+    deadline = time.monotonic() + timeout
+    while time.monotonic() < deadline:
+        time.sleep(interval)
+        result = _post_json(poll_url, {"device_code": device_code}, timeout=10)
+        status = result.get("status")
+        if status == "approved":
+            token, email = result.get("token"), result.get("email", "")
+            if not token:
+                raise AuthError(f"{poll_url} approved without a token")
+            save(token, email)
+            return Credentials(email=email, api_key=token)
+        if status == "pending":
+            continue
+        raise AuthError(f"sign-in {status}")
+
+    raise AuthError("timed out waiting for browser approval")

simantic/engine.py

@@ -0,0 +1,91 @@
+"""Loading the simulation engine into this process.
+
+`Simantic.Core` is a .NET library; `sim` is one face of it and this package is
+another. `simantic install` (or `$SIMANTIC_SIM`) gives us the directory that
+holds `sim`, `Simantic.Core.dll` and the runtime config, which is everything
+needed to host the engine here via pythonnet. Nothing is spawned: the Python
+objects *are* the session.
+
+One emulation per process — the engine keeps process-global state — so
+parallel runs are parallel processes (`ProcessPoolExecutor`).
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from functools import cache
+from pathlib import Path
+
+from . import install
+from ._locate import BinaryNotFound
+from .mcu import sim_binary
+
+ENV_DIR = "SIMANTIC_ENGINE_DIR"
+
+
+class EngineNotFound(RuntimeError):
+    """The engine assemblies could not be located or loaded."""
+
+
+def _is_engine(d: Path) -> bool:
+    return (d / "Simantic.Core.dll").exists() and (d / "sim.runtimeconfig.json").exists()
+
+
+def engine_dir(explicit: str | os.PathLike[str] | None = None, *, fetch: bool = True) -> Path:
+    """The directory holding Simantic.Core.dll and sim.runtimeconfig.json.
+
+    Order: an explicit path, $SIMANTIC_ENGINE_DIR, a development `sim` whose
+    publish directory is beside it ($SIMANTIC_SIM), then the managed install
+    under ~/.simantic/engine. When nothing is there, the engine is fetched
+    from the public release — so the first `Sim(...)` after `pip install`
+    just works.
+    """
+    candidates = []
+    if explicit is not None:
+        candidates.append(Path(explicit))
+    if os.environ.get(ENV_DIR):
+        candidates.append(Path(os.environ[ENV_DIR]))
+    try:
+        candidates.append(sim_binary().resolve().parent)
+    except BinaryNotFound:
+        pass
+    for d in candidates:
+        if _is_engine(d):
+            return d
+    managed = install.installed_engine()
+    if managed is not None:
+        return managed
+    if fetch:
+        try:
+            return install.install_engine()
+        except install.InstallError as exc:
+            raise EngineNotFound(f"could not fetch the engine: {exc}") from None
+    raise EngineNotFound(
+        f"Simantic.Core.dll not found. Run `simantic install engine`, or set ${ENV_DIR}."
+    )
+
+
+@cache
+def load(explicit: str | os.PathLike[str] | None = None):
+    """Host the .NET runtime and import Simantic.Core. Returns the Session namespace."""
+    d = engine_dir(explicit)
+    try:
+        from pythonnet import load as load_runtime
+    except ImportError as exc:  # pragma: no cover - dependency declared in pyproject
+        raise EngineNotFound("pythonnet is required to host the engine: pip install pythonnet") from exc
+    # A managed engine carries its own runtime in dotnet/; a development
+    # publish directory relies on the machine's ($DOTNET_ROOT / default).
+    bundled = d / "dotnet"
+    if (bundled / "host").is_dir():
+        load_runtime("coreclr", runtime_config=str(d / "sim.runtimeconfig.json"), dotnet_root=str(bundled))
+    else:
+        load_runtime("coreclr", runtime_config=str(d / "sim.runtimeconfig.json"))
+    import clr  # noqa: F401  (provided by pythonnet after load)
+
+    if str(d) not in sys.path:
+        sys.path.append(str(d))
+    clr.AddReference("Simantic.Core")
+    import Simantic.Core.Emulation.Session as session_ns  # type: ignore[import-not-found]
+
+    return session_ns

simantic/fixtures.py

@@ -0,0 +1,144 @@
+"""test.yaml fixture manifests: loading, and resolving from a model library.
+
+A fixture names an MCU (`mcu: STM32F401RE`), not a platform file. Normally
+`sim` resolves that name for you against your account; models are not
+distributed with this package.
+
+If you have a local model library, point $SIMANTIC_MCU_LIB at it and models
+resolve from there instead, without a round trip. That path is also what a
+fixture's `overlay` fragment needs, since an overlay edits platform text
+before it reaches the simulator. Resolution is delegated to the library's own
+tooling rather than reimplemented here, so the two cannot drift.
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+import tempfile
+from dataclasses import dataclass
+from functools import cache
+from pathlib import Path
+
+import yaml
+
+#: Points at a local model library. Optional: without it, models resolve
+#: through `sim` instead.
+MCU_LIB_ENV = "SIMANTIC_MCU_LIB"
+
+
+class ModelLibraryUnavailable(RuntimeError):
+    """No usable model library, so MCU names cannot be resolved locally."""
+
+
+@dataclass(frozen=True)
+class Manifest:
+    """A single-machine test.yaml. Multi-machine fixtures are not covered."""
+
+    path: Path
+    mcu: str
+    elf: str
+    timeout: int
+    expect: list[str]
+    expect_absent: list[str]
+    overlay: str | None = None
+
+    @property
+    def elf_path(self) -> Path:
+        return self.path.parent / self.elf
+
+    @property
+    def overlay_path(self) -> Path | None:
+        return self.path.parent / self.overlay if self.overlay else None
+
+
+class UnsupportedManifest(ValueError):
+    """The manifest describes a fixture this SDK cannot run yet."""
+
+
+def load_manifest(path: str | os.PathLike[str]) -> Manifest:
+    """Parse a test.yaml, or raise UnsupportedManifest with the reason."""
+    path = Path(path)
+    with open(path) as fh:
+        data = yaml.safe_load(fh) or {}
+
+    if "machines" in data:
+        raise UnsupportedManifest(
+            "multi-machine fixture: needs the sim --scenario runner, which this "
+            "SDK does not drive yet"
+        )
+    if "mcu" not in data:
+        raise UnsupportedManifest("manifest names no mcu")
+
+    return Manifest(
+        path=path,
+        mcu=data["mcu"],
+        elf=data["elf"],
+        timeout=int(data.get("timeout", 15)),
+        expect=list(data.get("expect") or []),
+        expect_absent=list(data.get("expect_absent") or []),
+        overlay=data.get("overlay"),
+    )
+
+
+def mcu_lib_root() -> Path:
+    """The configured model library, or raise ModelLibraryUnavailable."""
+    configured = os.environ.get(MCU_LIB_ENV)
+    if not configured:
+        raise ModelLibraryUnavailable(
+            f"set ${MCU_LIB_ENV} to a local model library to resolve MCU models"
+        )
+    root = Path(configured)
+    if not (root / "scripts" / "parse_replx.py").exists():
+        raise ModelLibraryUnavailable(
+            f"${MCU_LIB_ENV} is {root}, which has no scripts/parse_replx.py "
+            "(submodule not initialised?)"
+        )
+    return root
+
+
+@cache
+def resolved_models() -> Path:
+    """Resolve every model once per process; return the output dir.
+
+    parse_replx.py fills `using` directives and strips comments. The result
+    is cached for the process because resolving the whole library per test
+    would dominate a suite's runtime.
+    """
+    root = mcu_lib_root()
+    dest = Path(tempfile.mkdtemp(prefix="simantic-models-"))
+    subprocess.run(
+        [sys.executable, str(root / "scripts" / "parse_replx.py"), "models.yaml", str(dest)],
+        cwd=root,
+        check=True,
+        stdout=subprocess.DEVNULL,
+    )
+    return dest
+
+
+def platform_for(manifest: Manifest, workdir: Path) -> Path:
+    """The .replx to hand `sim --repl`, with any overlay fragment appended."""
+    return platform_path(manifest.mcu, manifest.overlay_path, workdir)
+
+
+def platform_path(mcu: str, overlay: Path | None, workdir: Path) -> Path:
+    """Resolve `mcu` from the local model library, appending `overlay` if given."""
+    base = resolved_models() / f"{mcu}.replx"
+    if not base.exists():
+        raise ModelLibraryUnavailable(f"mcu {mcu} is not in the model library")
+
+    if overlay is None:
+        return base
+
+    # The platform grammar has no comment syntax — `//` and `#` notes are
+    # stripped during resolution — so comment-only lines must go before the
+    # fragment is appended.
+    body = "\n".join(
+        line
+        for line in overlay.read_text().splitlines()
+        if not line.lstrip().startswith(("#", "//"))
+    )
+    merged = workdir / f"{mcu}-overlaid.replx"
+    merged.write_text(base.read_text().rstrip() + "\n\n" + body.strip() + "\n")
+    return merged