maestro-framework 0.1.0__py3-none-any.whl

maestro_core/__init__.py

@@ -0,0 +1,43 @@
+"""MAESTRO core — the headless heart of the platform.
+
+MAESTRO (Modular Automotive Embedded System Test, Reporting & Orchestration) is an
+offline-capable test-automation platform for automotive Hardware-in-the-Loop
+(HIL) and embedded device testing.
+
+``maestro_core`` contains everything needed to execute a test *scenario* with no
+server and no UI:
+
+* :mod:`maestro_core.scenario` — the versioned JSON scenario model (the single
+  source of truth authored on the canvas) plus validation and JSON-Schema export.
+* :mod:`maestro_core.steps` — the step registry, the per-step execution context,
+  the built-in step library, and the generic script-wrapping adapter.
+* :mod:`maestro_core.drivers` — thin adapters that shell out to the user's own
+  device tools (turboadb, turbossh, power scripts, DLT, webcam), plus fully
+  functional fake drivers for hardware-free testing.
+* :mod:`maestro_core.detect` — device detectors (serial, adb, camera, ssh).
+* :mod:`maestro_core.engine` — the pytest plugin and small generic runner that
+  turn a scenario into executed, reported tests.
+* :mod:`maestro_core.endurance` — the long-running cycle loop and stop conditions.
+* :mod:`maestro_core.reporting` — the attachment pipeline and Allure/JUnit hooks.
+* :mod:`maestro_core.config` — layered TOML configuration loading.
+
+Author:
+    Naveen Daniel Kennedy <nvnkennedy@gmail.com>
+"""
+
+from __future__ import annotations
+
+#: Semantic version of the MAESTRO core package (single source of truth; the
+#: build backend reads this string to stamp the wheel).
+__version__ = "0.1.0"
+
+#: Human-readable product name, backronym, and tagline used across the UI, the
+#: About page, and the docs. MAESTRO conducts the test bench the way a maestro
+#: leads an orchestra — keeping devices, scenarios, and endurance cycles in time —
+#: which is fitting for automotive infotainment, where the head unit conducts the
+#: vehicle's audio, video, and connectivity.
+PRODUCT_NAME = "MAESTRO"
+PRODUCT_BACKRONYM = "Modular Automotive Embedded System Test, Reporting & Orchestration"
+PRODUCT_TAGLINE = "Automotive embedded test orchestration"
+
+__all__ = ["PRODUCT_BACKRONYM", "PRODUCT_NAME", "PRODUCT_TAGLINE", "__version__"]

maestro_core/cli.py

@@ -0,0 +1,180 @@
+"""Headless command-line interface for ``maestro-core``.
+
+Run, validate, and inspect scenarios with no server and no UI:
+
+* ``maestro-core run <scenario.json> --bench <bench.toml>`` — execute a scenario.
+* ``maestro-core validate <scenario.json>`` — report validation issues.
+* ``maestro-core schema [--out file]`` — export the scenario JSON-Schema.
+* ``maestro-core steps`` — list every registered step.
+* ``maestro-core detect [--host H]`` — run device detectors and print proposals.
+
+Author:
+    Naveen Daniel Kennedy <nvnkennedy@gmail.com>
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from datetime import datetime
+from pathlib import Path
+
+from maestro_core import PRODUCT_BACKRONYM, PRODUCT_NAME, __version__
+from maestro_core.config import build_devices, load_bench_toml
+from maestro_core.detect import run_detection
+from maestro_core.engine import RunOptions, run_scenario
+from maestro_core.engine.plugin import ScenarioCase, run_via_pytest
+from maestro_core.reporting import write_junit, write_run_record
+from maestro_core.scenario import (
+    load_scenario_file,
+    parse_scenario,
+    scenario_json_schema,
+    validate_scenario,
+)
+from maestro_core.steps import all_steps, known_step_names, load_all_steps
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    """Construct the argument parser for the CLI."""
+    parser = argparse.ArgumentParser(
+        prog="maestro-core", description=f"{PRODUCT_NAME} — {PRODUCT_BACKRONYM}"
+    )
+    parser.add_argument("-V", "--version", action="version", version=f"maestro-core {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    run = sub.add_parser("run", help="run a scenario on a bench")
+    run.add_argument("scenario", help="path to the scenario JSON")
+    run.add_argument("--bench", required=True, help="path to the bench TOML")
+    run.add_argument("--out", default=None, help="output directory for this run")
+    run.add_argument("--mode", choices=["serial", "parallel", "step"], default="serial")
+    run.add_argument("--user-steps", default=None, help="directory of drop-in step scripts")
+    run.add_argument(
+        "--pytest", action="store_true", help="execute through pytest (writes an Allure report)"
+    )
+
+    validate = sub.add_parser("validate", help="validate a scenario")
+    validate.add_argument("scenario", help="path to the scenario JSON")
+
+    schema = sub.add_parser("schema", help="export the scenario JSON-Schema")
+    schema.add_argument("--out", default=None, help="write the schema here instead of stdout")
+
+    sub.add_parser("steps", help="list registered steps")
+
+    detect = sub.add_parser("detect", help="run device detectors")
+    detect.add_argument("--host", default=None, help="ssh host to probe")
+    detect.add_argument("--port", type=int, default=22, help="ssh port to probe")
+    return parser
+
+
+def _cmd_run(args: argparse.Namespace) -> int:
+    """Execute the ``run`` subcommand."""
+    load_all_steps(args.user_steps)
+    scenario = load_scenario_file(args.scenario, validate=True, known_steps=known_step_names())
+    bench = load_bench_toml(args.bench)
+    stamp = datetime.now().strftime("%Y%m%d-%H%M%S")
+    out = (
+        Path(args.out)
+        if args.out
+        else Path(".maestro") / "runs" / f"{scenario.metadata.id}-{stamp}"
+    )
+    out.mkdir(parents=True, exist_ok=True)
+
+    devices = build_devices(bench, output_dir=out / "artifacts")
+    options = RunOptions(bench=bench.name, mode=args.mode, user_steps_dir=args.user_steps)
+
+    if args.pytest:
+        case = ScenarioCase(
+            id=f"{scenario.metadata.id}[{bench.name}]",
+            scenario=scenario,
+            devices=devices,
+            run_dir=out,
+            options=options,
+        )
+        results = run_via_pytest([case], out)
+        run = results.get(case.id)
+        if run is None:
+            print("error: the scenario did not run under pytest", file=sys.stderr)
+            return 2
+    else:
+        run = run_scenario(scenario, devices, out, options=options)
+
+    write_run_record(run, out / "run.json")
+    write_junit(run, out / "junit.xml")
+
+    print(f"{run.scenario_id} on {run.bench}: {run.status.upper()}")
+    print(f"  steps: {run.summary.get('passed', 0)} passed, {run.summary.get('failed', 0)} failed")
+    if run.is_endurance:
+        for group_id, rollup in run.summary.get("endurance", {}).items():
+            print(
+                f"  endurance[{group_id}]: {rollup['passed']}/{rollup['completed_cycles']} cycles "
+                f"passed, first failure: {rollup['first_failure_cycle']}"
+            )
+    print(f"  output: {out}")
+    return 0 if run.status == "passed" else 1
+
+
+def _cmd_validate(args: argparse.Namespace) -> int:
+    """Execute the ``validate`` subcommand."""
+    load_all_steps(None)
+    scenario = parse_scenario(Path(args.scenario).read_text(encoding="utf-8"))
+    issues = validate_scenario(scenario, known_steps=known_step_names())
+    if not issues:
+        print("valid: no issues found")
+        return 0
+    for issue in issues:
+        where = f" @{issue.location}" if issue.location else ""
+        print(f"[{issue.severity}] {issue.code}{where}: {issue.message}")
+    return 0 if all(i.severity != "error" for i in issues) else 1
+
+
+def _cmd_schema(args: argparse.Namespace) -> int:
+    """Execute the ``schema`` subcommand."""
+    text = json.dumps(scenario_json_schema(), indent=2)
+    if args.out:
+        Path(args.out).write_text(text + "\n", encoding="utf-8")
+        print(f"wrote schema to {args.out}")
+    else:
+        print(text)
+    return 0
+
+
+def _cmd_steps(_: argparse.Namespace) -> int:
+    """Execute the ``steps`` subcommand."""
+    load_all_steps(None)
+    for name, spec in sorted(all_steps().items()):
+        params = ", ".join(f"{p.name}:{p.kind}{'' if p.required else '?'}" for p in spec.params)
+        suffix = " [free-form]" if spec.freeform else ""
+        print(f"{name}  ({spec.category}){suffix}")
+        if params:
+            print(f"    {params}")
+    return 0
+
+
+def _cmd_detect(args: argparse.Namespace) -> int:
+    """Execute the ``detect`` subcommand."""
+    proposals, errors = run_detection(host=args.host, port=args.port)
+    output = {
+        "proposals": {name: [p.model_dump() for p in items] for name, items in proposals.items()},
+        "errors": errors,
+    }
+    print(json.dumps(output, indent=2))
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    """CLI entry point. Returns a process exit code."""
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+    handlers = {
+        "run": _cmd_run,
+        "validate": _cmd_validate,
+        "schema": _cmd_schema,
+        "steps": _cmd_steps,
+        "detect": _cmd_detect,
+    }
+    return handlers[args.command](args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

maestro_core/config/__init__.py

@@ -0,0 +1,32 @@
+"""MAESTRO configuration — typed settings, layered TOML, and the bench bridge.
+
+Author:
+    Naveen Daniel Kennedy <nvnkennedy@gmail.com>
+"""
+
+from __future__ import annotations
+
+from maestro_core.config.devices import build_devices, driver_name_for
+from maestro_core.config.loader import (
+    deep_merge,
+    load_bench_toml,
+    load_layered,
+    load_toml,
+    write_bench_toml,
+)
+from maestro_core.config.models import BenchConfig, DeviceConfig
+from maestro_core.config.settings import MaestroSettings, get_settings
+
+__all__ = [
+    "BenchConfig",
+    "DeviceConfig",
+    "MaestroSettings",
+    "build_devices",
+    "deep_merge",
+    "driver_name_for",
+    "get_settings",
+    "load_bench_toml",
+    "load_layered",
+    "load_toml",
+    "write_bench_toml",
+]

maestro_core/config/devices.py

@@ -0,0 +1,152 @@
+"""Build a live :class:`~maestro_core.drivers.base.Devices` bundle from a bench.
+
+This is the bridge between configuration (data) and drivers (behaviour): it picks
+the right driver for each device, maps the device's endpoint fields onto that
+driver's constructor arguments, instantiates it, and files it under the right
+capability (power / camera / log) or device role.
+
+Author:
+    Naveen Daniel Kennedy <nvnkennedy@gmail.com>
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any
+
+from maestro_core.config.models import BenchConfig, DeviceConfig
+from maestro_core.drivers.base import (
+    CameraController,
+    DeviceController,
+    Devices,
+    LogController,
+    PowerController,
+)
+from maestro_core.drivers.registry import create_driver
+from maestro_core.errors import ConfigError
+
+#: Maps a device ``type`` to the driver that handles it.
+_DRIVER_BY_TYPE = {
+    "android": "turboadb",
+    "adb": "turboadb",
+    "qnx": "turbossh",
+    "linux": "turbossh",
+    "ssh": "turbossh",
+    "camera": "webcam",
+    "power": "power",
+    "dlt": "dlt",
+}
+
+
+def driver_name_for(device: DeviceConfig) -> str:
+    """Return the driver name for a device (explicit ``driver``, else by ``type``).
+
+    A ``type`` that is not a known category is assumed to *be* a driver name (so
+    ``type = "fake_power"`` works directly).
+    """
+    if device.driver:
+        return device.driver
+    return _DRIVER_BY_TYPE.get(device.type.lower(), device.type)
+
+
+def _driver_kwargs(device: DeviceConfig, driver_name: str, output_dir: Path) -> dict[str, Any]:
+    """Map a device's fields onto the named driver's constructor arguments."""
+    if driver_name == "turboadb":
+        kwargs: dict[str, Any] = {
+            "serial": device.adb_serial,
+            "adb_path": device.adb_path,
+            "adb_host": device.adb_host,
+            "adb_port": device.adb_port,
+            "timeout": device.timeout,
+        }
+    elif driver_name == "turbossh":
+        kwargs = {
+            "host": device.ssh_host,
+            "user": device.ssh_user,
+            "port": device.ssh_port or 22,
+            "key": device.ssh_key,
+            "use_stored": device.ssh_use_stored,
+            "service": device.ssh_service,
+            "domain": device.ssh_domain,
+            "timeout": device.timeout,
+        }
+    elif driver_name in ("webcam", "fake_camera"):
+        camera_index = device.camera_index if device.camera_index is not None else device.index
+        kwargs = {
+            "index": camera_index if camera_index is not None else 0,
+            "name": device.camera_name or device.name,
+            "output_dir": str(output_dir),
+        }
+        if driver_name == "fake_camera":
+            kwargs = {"output_dir": str(output_dir)}
+    elif driver_name == "power":
+        kwargs = {
+            "script": device.script,
+            "com_port": device.com_port,
+            "channel": device.power_channel,
+            "python": device.python,
+            "timeout": device.timeout,
+        }
+    elif driver_name in ("dlt",):
+        kwargs = {
+            "ecu": device.dlt_ecu or "ECU1",
+            "host": device.dlt_host,
+            "port": device.dlt_port,
+            "output_dir": str(output_dir),
+        }
+    elif driver_name == "fake_log":
+        kwargs = {"output_dir": str(output_dir)}
+    else:
+        kwargs = {}
+
+    # Drop unset values so each driver's own defaults apply, then layer extras.
+    kwargs = {key: value for key, value in kwargs.items() if value is not None}
+    kwargs.update(device.extra_options())
+    return kwargs
+
+
+def build_devices(
+    bench: BenchConfig,
+    *,
+    output_dir: str | Path,
+    factory: Callable[..., Any] = create_driver,
+) -> Devices:
+    """Instantiate every device on a bench and bundle them for the engine.
+
+    Args:
+        bench: The bench configuration.
+        output_dir: Directory where camera/DLT drivers write their artifacts.
+        factory: Driver factory (injectable for tests; defaults to the registry).
+
+    Returns:
+        A :class:`Devices` bundle. The first power/camera/log device fills the
+        matching capability slot; every command-capable device is addressable by
+        its role.
+
+    Raises:
+        ConfigError: If a device resolves to a controller of an unknown kind.
+    """
+    out = Path(output_dir)
+    roles: dict[str, DeviceController] = {}
+    power: PowerController | None = None
+    camera: CameraController | None = None
+    log: LogController | None = None
+
+    for role, device in bench.devices.items():
+        name = driver_name_for(device)
+        controller = factory(name, **_driver_kwargs(device, name, out))
+        if isinstance(controller, PowerController):
+            power = power or controller
+        elif isinstance(controller, LogController):
+            log = log or controller
+        elif isinstance(controller, CameraController):
+            camera = camera or controller
+        elif isinstance(controller, DeviceController):
+            roles[role] = controller
+        else:
+            raise ConfigError(
+                f"device '{role}' resolved to driver '{name}', which is not a known controller type"
+            )
+
+    return Devices(roles=roles, power=power, camera=camera, log=log)

maestro_core/config/loader.py

@@ -0,0 +1,111 @@
+"""Layered TOML configuration loading and bench file I/O.
+
+Configuration is layered ``global -> project -> bench -> user`` (later layers win),
+all in TOML. The standard library reads TOML (``tomllib``); ``tomli_w`` writes the
+auto-managed bench files. Secrets never live in these files — they come from
+environment variables or the OS keyring (see :mod:`maestro_core.config.settings`).
+
+Author:
+    Naveen Daniel Kennedy <nvnkennedy@gmail.com>
+"""
+
+from __future__ import annotations
+
+import tomllib
+from pathlib import Path
+from typing import Any
+
+import tomli_w
+
+from maestro_core.config.models import BenchConfig, DeviceConfig
+from maestro_core.errors import ConfigError
+
+
+def load_toml(path: str | Path) -> dict[str, Any]:
+    """Read a TOML file into a dict.
+
+    Raises:
+        ConfigError: If the file cannot be parsed.
+    """
+    try:
+        with Path(path).open("rb") as handle:
+            return tomllib.load(handle)
+    except (OSError, tomllib.TOMLDecodeError) as exc:
+        raise ConfigError(f"could not read TOML file {path}: {exc}") from exc
+
+
+def deep_merge(base: dict[str, Any], override: dict[str, Any]) -> dict[str, Any]:
+    """Recursively merge ``override`` onto ``base`` (override wins on conflict)."""
+    result = dict(base)
+    for key, value in override.items():
+        existing = result.get(key)
+        if isinstance(existing, dict) and isinstance(value, dict):
+            result[key] = deep_merge(existing, value)
+        else:
+            result[key] = value
+    return result
+
+
+def load_layered(paths: list[str | Path]) -> dict[str, Any]:
+    """Merge a list of TOML files in order (later files override earlier ones).
+
+    Missing files are skipped, so a partial set of layers is fine.
+    """
+    merged: dict[str, Any] = {}
+    for path in paths:
+        candidate = Path(path)
+        if candidate.exists():
+            merged = deep_merge(merged, load_toml(candidate))
+    return merged
+
+
+def load_bench_toml(path: str | Path) -> BenchConfig:
+    """Load a bench file (``[bench]`` table + ``[devices.<role>]`` tables).
+
+    Args:
+        path: The bench TOML file.
+
+    Returns:
+        The parsed :class:`BenchConfig`.
+
+    Raises:
+        ConfigError: If the file is missing or malformed.
+    """
+    data = load_toml(path)
+    bench_table = dict(data.get("bench", {}))
+    device_tables = data.get("devices", {})
+    if not isinstance(device_tables, dict):
+        raise ConfigError(f"{path}: [devices] must be a table of device entries")
+    devices = {role: DeviceConfig(**cfg) for role, cfg in device_tables.items()}
+    try:
+        return BenchConfig(**bench_table, devices=devices)
+    except Exception as exc:  # pydantic ValidationError -> typed ConfigError
+        raise ConfigError(f"{path}: invalid bench configuration: {exc}") from exc
+
+
+def write_bench_toml(bench: BenchConfig, path: str | Path) -> Path:
+    """Write a bench config to TOML (the format detection produces).
+
+    Args:
+        bench: The bench configuration to serialise.
+        path: Destination file (parent directories are created).
+
+    Returns:
+        The path that was written.
+    """
+    bench_table = bench.model_dump(exclude_none=True, exclude={"devices"})
+    bench_table = {key: value for key, value in bench_table.items() if value != ""}
+    devices_table = {
+        role: device.model_dump(exclude_none=True, exclude_defaults=False)
+        for role, device in bench.devices.items()
+    }
+    # Drop empty 'options' dicts so the file stays tidy.
+    for entry in devices_table.values():
+        if entry.get("options") == {}:
+            entry.pop("options", None)
+    document: dict[str, Any] = {"bench": bench_table, "devices": devices_table}
+    target = Path(path)
+    target.parent.mkdir(parents=True, exist_ok=True)
+    with target.open("wb") as handle:
+        tomli_w.dump(document, handle)
+    return target

maestro_core/config/models.py

@@ -0,0 +1,86 @@
+"""Configuration models — benches and devices.
+
+A bench TOML (auto-managed by "Detect devices") describes a test rig: the host,
+its RDP target, and one entry per attached device. These models parse that file
+and are the input to :func:`maestro_core.config.devices.build_devices`, which
+turns them into live driver instances.
+
+Unknown keys are accepted (``extra="allow"``) so a newer detector or a hand-edited
+file can carry fields this version does not know about; they are forwarded to the
+driver as extra keyword arguments.
+
+Author:
+    Naveen Daniel Kennedy <nvnkennedy@gmail.com>
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class DeviceConfig(BaseModel):
+    """One device on a bench (an adb target, ssh host, camera, power, or DLT)."""
+
+    model_config = ConfigDict(extra="allow")
+
+    type: str = Field(default="linux", description="Device type or a driver name.")
+    driver: str | None = Field(default=None, description="Explicit driver name (overrides type).")
+
+    # SSH endpoint
+    ssh_host: str | None = None
+    ssh_user: str | None = None
+    ssh_port: int | None = None
+    ssh_key: str | None = None
+    ssh_use_stored: bool = False
+    ssh_service: str | None = None
+    ssh_domain: str | None = None
+
+    # ADB endpoint
+    adb_path: str | None = None
+    adb_serial: str | None = None
+    adb_host: str | None = None
+    adb_port: int | None = None
+
+    # Camera endpoint (both ``camera_*`` and the terse ``index``/``name`` are accepted)
+    camera_index: int | None = None
+    camera_name: str | None = None
+    index: int | None = None
+    name: str | None = None
+
+    # DLT endpoint
+    dlt_ecu: str | None = None
+    dlt_host: str | None = None
+    dlt_port: int | None = None
+
+    # Power endpoint
+    power_channel: str | None = None
+    com_port: str | None = None
+    script: str | None = None
+    python: str | None = None
+
+    # Generic
+    timeout: float | None = None
+    options: dict[str, Any] = Field(
+        default_factory=dict, description="Extra keyword arguments passed to the driver."
+    )
+
+    def extra_options(self) -> dict[str, Any]:
+        """Return ``options`` merged with any unknown (``extra``) keys."""
+        merged = dict(self.options)
+        merged.update(self.__pydantic_extra__ or {})
+        return merged
+
+
+class BenchConfig(BaseModel):
+    """A test bench: a host with a set of attached devices."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    name: str = Field(min_length=1)
+    host_os: str = "windows"
+    rdp: str | None = Field(default=None, description="RDP target host/IP for the bench.")
+    project: str | None = None
+    notes: str = ""
+    devices: dict[str, DeviceConfig] = Field(default_factory=dict)

maestro_core/config/settings.py

@@ -0,0 +1,60 @@
+"""Typed, environment-driven settings.
+
+These are the knobs that change per *installation* (where data lives, which
+database to use) rather than per *bench* (which is the TOML files). Values come
+from ``MAESTRO_*`` environment variables or an optional ``.env`` file. Secrets
+(SMTP password, Xray token, …) are read from the environment only — never written
+to a config file (brief §13).
+
+Author:
+    Naveen Daniel Kennedy <nvnkennedy@gmail.com>
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from pydantic import Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+def _default_home() -> Path:
+    """Return the default MAESTRO data directory (``~/.maestro``)."""
+    return Path.home() / ".maestro"
+
+
+class MaestroSettings(BaseSettings):
+    """Installation-level settings, configurable via ``MAESTRO_*`` env vars."""
+
+    model_config = SettingsConfigDict(
+        env_prefix="MAESTRO_", env_file=".env", env_file_encoding="utf-8", extra="ignore"
+    )
+
+    home: Path = Field(default_factory=_default_home, description="Base data directory.")
+    config_dir: Path = Field(default=Path("config"), description="Where TOML config lives.")
+    runs_dir: Path = Field(
+        default_factory=lambda: _default_home() / "runs", description="Where run artifacts go."
+    )
+    user_steps_dir: Path | None = Field(
+        default=None, description="Optional folder of drop-in step scripts."
+    )
+    database_url: str = Field(
+        default="sqlite:///./maestro.db", description="SQLAlchemy database URL."
+    )
+
+    def global_toml(self) -> Path:
+        """Return the path to the global config TOML."""
+        return self.config_dir / "global.toml"
+
+    def project_toml(self, project: str) -> Path:
+        """Return the path to a project's config TOML."""
+        return self.config_dir / "projects" / f"{project}.toml"
+
+    def bench_toml(self, bench: str) -> Path:
+        """Return the path to a bench's config TOML."""
+        return self.config_dir / "benches" / f"{bench}.toml"
+
+
+def get_settings() -> MaestroSettings:
+    """Build a fresh :class:`MaestroSettings` from the current environment."""
+    return MaestroSettings()