trunft 0.1.0__py3-none-any.whl

trunft/__init__.py

@@ -0,0 +1,3 @@
+"""TruNFT - one platform for non-functional testing across Web and Mobile."""
+
+__version__ = "0.1.0"

trunft/api.py

@@ -0,0 +1,197 @@
+"""Service layer shared by the CLI and the MCP server.
+
+Everything returns plain JSON-serialisable dicts so either interface can render it.
+Long runs (soak tests last hours) execute in background threads via ``RunManager``.
+"""
+from __future__ import annotations
+
+import importlib.util
+import json
+import threading
+import uuid
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from trunft import __version__, reporting
+from trunft.core.config import Config, load_config
+from trunft.core.models import NFTResult, Platform
+from trunft.core.pillar import all_pillars
+from trunft.core.runner import PlanItem, build_plan, execute, new_run_dir, reports_root
+from trunft.core.tooling import KNOWN_TOOLS, which
+
+_SECRET_HINTS = ("token", "password", "secret", "authorization", "apikey", "api_key", "cookie")
+
+
+# --- discovery -------------------------------------------------------------------
+def capabilities() -> dict[str, Any]:
+    """Pillars, their test types, descriptions and per-platform applicability."""
+    return {
+        "version": __version__,
+        "platforms": [p.value for p in Platform],
+        "pillars": [
+            {
+                "name": p.name,
+                "title": p.title,
+                "test_types": [
+                    {"name": t, "description": d, "required_tools": p.tools.get(t, []),
+                     "platforms": [pl.value for pl in Platform if p.supports(pl, t)]}
+                    for t, d in p.test_types.items()
+                ],
+            }
+            for p in all_pillars().values()
+        ],
+    }
+
+
+def doctor() -> dict[str, Any]:
+    tools = {t: {"available": bool(which(t)), "purpose": why} for t, why in KNOWN_TOOLS.items()}
+    tools["playwright"] = {"available": importlib.util.find_spec("playwright") is not None,
+                           "purpose": "Compatibility: browser/device matrix (pip install 'trunft[web]')"}
+    return {"tools": tools}
+
+
+def environments(root: Path) -> list[str]:
+    return sorted(p.stem for p in (Path(root) / "config" / "environments").glob("*.yaml"))
+
+
+def _redact(node: Any) -> Any:
+    if isinstance(node, dict):
+        return {k: ("***" if any(h in str(k).lower() for h in _SECRET_HINTS) and v else _redact(v))
+                for k, v in node.items()}
+    if isinstance(node, list):
+        return [_redact(v) for v in node]
+    return node
+
+
+def effective_config(root: Path, environment: str | None = None) -> dict[str, Any]:
+    """Merged config for an environment, with secret-looking values redacted."""
+    cfg = load_config(root, environment)
+    return {"environment": cfg.environment, "config": _redact(cfg.data)}
+
+
+# --- planning --------------------------------------------------------------------
+def _plan(cfg: Config, platforms, pillars, test_types) -> list[PlanItem]:
+    return build_plan(cfg, [Platform(p) for p in platforms] if platforms else None,
+                      pillars or None, test_types or None)
+
+
+def plan(root: Path, environment: str | None = None, platforms: list[str] | None = None,
+         pillars: list[str] | None = None, test_types: list[str] | None = None) -> dict[str, Any]:
+    cfg = load_config(root, environment)
+    items = _plan(cfg, platforms, pillars, test_types)
+    return {"environment": cfg.environment, "count": len(items),
+            "items": [{"platform": i.platform.value, "pillar": i.pillar.name, "test_type": i.test_type}
+                      for i in items]}
+
+
+# --- execution -------------------------------------------------------------------
+@dataclass
+class RunHandle:
+    run_id: str
+    environment: str
+    output_dir: Path
+    total: int
+    dry_run: bool
+    state: str = "running"          # running | completed | cancelled | crashed
+    results: list[NFTResult] = field(default_factory=list)
+    error: str = ""
+    cancel_requested: bool = False
+    thread: threading.Thread | None = None
+
+    def snapshot(self, include_results: bool = True) -> dict[str, Any]:
+        failures = [r for r in self.results if r.is_failure]
+        data = {
+            "run_id": self.run_id, "state": self.state, "environment": self.environment,
+            "dry_run": self.dry_run, "output_dir": str(self.output_dir),
+            "progress": {"done": len(self.results), "total": self.total},
+            "summary": reporting.summarize(self.results), "has_failures": bool(failures),
+        }
+        if self.error:
+            data["error"] = self.error
+        if include_results:
+            data["results"] = [r.to_dict() for r in self.results]
+        return data
+
+
+class RunManager:
+    """Starts runs in background threads and tracks them (in-process, per server)."""
+
+    def __init__(self) -> None:
+        self._runs: dict[str, RunHandle] = {}
+        self._lock = threading.Lock()
+
+    def start(self, root: Path, environment: str | None = None, platforms: list[str] | None = None,
+              pillars: list[str] | None = None, test_types: list[str] | None = None,
+              dry_run: bool = False) -> RunHandle:
+        cfg = load_config(root, environment)
+        items = _plan(cfg, platforms, pillars, test_types)   # validate before spawning
+        out = new_run_dir(cfg)
+        run_id = f"{out.name}-{uuid.uuid4().hex[:6]}"
+        out = out.with_name(run_id)
+        handle = RunHandle(run_id, cfg.environment, out, len(items), dry_run)
+
+        def work() -> None:
+            try:
+                execute(cfg, items, dry_run=dry_run, out_dir=out, on_result=handle.results.append,
+                        should_stop=lambda: handle.cancel_requested)
+                handle.state = "cancelled" if handle.cancel_requested else "completed"
+            except Exception as exc:  # pragma: no cover - defensive
+                handle.state, handle.error = "crashed", f"{type(exc).__name__}: {exc}"
+
+        handle.thread = threading.Thread(target=work, name=f"trunft-{run_id}", daemon=True)
+        with self._lock:
+            self._runs[run_id] = handle
+        handle.thread.start()
+        return handle
+
+    def get(self, run_id: str) -> RunHandle | None:
+        return self._runs.get(run_id)
+
+    def cancel(self, run_id: str) -> RunHandle | None:
+        handle = self._runs.get(run_id)
+        if handle and handle.state == "running":
+            handle.cancel_requested = True
+        return handle
+
+    def active(self) -> list[RunHandle]:
+        return [h for h in self._runs.values() if h.state == "running"]
+
+
+def run_sync(root: Path, environment: str | None = None, platforms: list[str] | None = None,
+             pillars: list[str] | None = None, test_types: list[str] | None = None,
+             dry_run: bool = False, output_root: Path | None = None, on_result=None):
+    cfg = load_config(root, environment)
+    items = _plan(cfg, platforms, pillars, test_types)
+    results, out, reports = execute(cfg, items, output_root, dry_run=dry_run, on_result=on_result)
+    return cfg, items, results, out, reports
+
+
+# --- historical reports ----------------------------------------------------------
+def list_reports(root: Path, limit: int = 20) -> list[dict[str, Any]]:
+    cfg = load_config(root)
+    base = reports_root(cfg)
+    runs = sorted((p for p in base.glob("*/results.json")), key=lambda p: p.parent.name, reverse=True)
+    out = []
+    for path in runs[:limit]:
+        try:
+            data = json.loads(path.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError):
+            continue
+        out.append({"run": path.parent.name, "meta": data.get("meta"), "summary": data.get("summary")})
+    return out
+
+
+def read_report(root: Path, run: str, only_failures: bool = False) -> dict[str, Any]:
+    cfg = load_config(root)
+    base = reports_root(cfg).resolve()
+    path = (base / run / "results.json").resolve()
+    if base not in path.parents:
+        raise ValueError("run must be a report folder name, e.g. 20261105-161739-dev")
+    if not path.exists():
+        raise FileNotFoundError(f"No results.json for run '{run}'")
+    data = json.loads(path.read_text(encoding="utf-8"))
+    if only_failures:
+        data["results"] = [r for r in data["results"] if r["status"] in ("failed", "error")]
+    data["report_dir"] = str(path.parent)
+    return data

trunft/cli.py

@@ -0,0 +1,219 @@
+"""TruNFT command line. Mirrors the MCP server: both sit on trunft.api.
+
+    trunft init [path]                           # create a project (config, workloads, ...)
+    trunft list [--json]                         # pillars x test types x platforms
+    trunft doctor [--json]                       # which external tools are installed
+    trunft setup [--tool k6] [--dry-run]         # install missing tools
+    trunft plan -e staging --pillar performance  # preview, executes nothing
+    trunft run -e staging -p web --pillar performance -t load
+    trunft run --dry-run
+    trunft reports                               # recent runs on disk
+    trunft report <run> [--failures]             # one run's results
+    trunft mcp [--transport stdio|streamable-http]   # start the MCP server
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+from trunft import __version__, api
+from trunft.core.config import ConfigError
+from trunft.core.models import NFTResult, Platform, Status
+
+_ICON = {Status.PASSED: "PASS", Status.FAILED: "FAIL", Status.ERROR: "ERR ",
+         Status.SKIPPED: "SKIP", Status.NOT_IMPLEMENTED: "TODO"}
+
+
+def _dump(data: Any) -> int:
+    print(json.dumps(data, indent=2, default=str))
+    return 0
+
+
+def cmd_list(args: argparse.Namespace) -> int:
+    caps = api.capabilities()
+    if args.json:
+        return _dump(caps)
+    plats = caps["platforms"]
+    print(f"{'pillar / test type':42}" + "".join(f"{p:>16}" for p in plats))
+    for pillar in caps["pillars"]:
+        print(f"\n{pillar['title']}  [{pillar['name']}]")
+        for t in pillar["test_types"]:
+            print(f"  {t['name']:40}" + "".join(f"{('x' if p in t['platforms'] else '-'):>16}" for p in plats))
+    return 0
+
+
+def cmd_doctor(args: argparse.Namespace) -> int:
+    tools = api.doctor()["tools"]
+    if args.json:
+        return _dump(tools)
+    print("External tools (optional - tests needing a missing tool are SKIPPED):\n")
+    for name, info in tools.items():
+        print(f"  [{'ok' if info['available'] else '--'}] {name:10} {info['purpose']}")
+    from trunft.setup_tools import OS, RECIPES
+
+    installable = [r.tool for r in RECIPES if not tools.get(r.tool, {}).get("available", True) and r.steps.get(OS)]
+    if installable:
+        print(f"\nInstall missing tools ({', '.join(installable)}) with: trunft setup   (preview: --dry-run)")
+    return 0
+
+
+def cmd_init(args: argparse.Namespace) -> int:
+    from trunft.scaffold import init_project
+
+    target = Path(args.path).resolve()
+    written, skipped = init_project(target, force=args.force)
+    print(f"TruNFT project at {target}\n")
+    for rel in written:
+        print(f"  + {rel}")
+    for rel in skipped:
+        print(f"  = {rel} (exists, kept - use --force to overwrite)")
+    print("\nNext: edit config/environments/*.yaml (target URLs), then `trunft doctor` and `trunft run --dry-run`.")
+    return 0
+
+
+def cmd_setup(args: argparse.Namespace) -> int:
+    from trunft.setup_tools import setup
+
+    print(f"TruNFT setup{' (dry run)' if args.dry_run else ''}\n")
+    outcome = setup(args.tool, dry_run=args.dry_run)
+    return 1 if "failed" in outcome.values() else 0
+
+
+def cmd_plan(args: argparse.Namespace) -> int:
+    data = api.plan(Path(args.root), args.env, args.platform, args.pillar, args.type)
+    if args.json:
+        return _dump(data)
+    print(f"env={data['environment']} | {data['count']} test(s)\n")
+    for i in data["items"]:
+        print(f"  {i['platform']:15} {i['pillar']:14} {i['test_type']}")
+    return 0
+
+
+def _print_result(r: NFTResult) -> None:
+    print(f"  [{_ICON[r.status]}] {r.platform.value:15} {r.pillar:14} {r.test_type:20} {r.message}")
+    for b in r.threshold_breaches:
+        print(f"         ! {b}")
+
+
+def cmd_run(args: argparse.Namespace) -> int:
+    print(f"TruNFT {__version__}{' | DRY RUN' if args.dry_run else ''}\n")
+    cfg, _, results, out, reports = api.run_sync(
+        Path(args.root), args.env, args.platform, args.pillar, args.type, dry_run=args.dry_run,
+        output_root=Path(args.output) if args.output else None, on_result=_print_result)
+    failures = [r for r in results if r.is_failure]
+    print(f"\nenv={cfg.environment} | reports: {out}")
+    for p in reports:
+        print(f"  - {p.name}")
+    print(f"\n{len(results) - len(failures)}/{len(results)} without failures"
+          + (f"; {len(failures)} FAILED/ERROR" if failures else ""))
+    return 1 if failures else 0
+
+
+def cmd_reports(args: argparse.Namespace) -> int:
+    runs = api.list_reports(Path(args.root), args.limit)
+    if args.json:
+        return _dump(runs)
+    if not runs:
+        print("No reports yet.")
+    for r in runs:
+        s = r["summary"] or {}
+        print(f"  {r['run']:34} total={s.get('total', 0):<4} passed={s.get('passed', 0):<4} "
+              f"failed={s.get('failed', 0):<4} error={s.get('error', 0):<4} dry_run={(r['meta'] or {}).get('dry_run')}")
+    return 0
+
+
+def cmd_report(args: argparse.Namespace) -> int:
+    data = api.read_report(Path(args.root), args.run, args.failures)
+    if args.json:
+        return _dump(data)
+    print(f"{args.run} | {data['summary']}\n{data['report_dir']}\n")
+    for r in data["results"]:
+        print(f"  [{r['status']:>15}] {r['platform']:15} {r['pillar']:14} {r['test_type']:20} {r['message']}")
+        for b in r["threshold_breaches"]:
+            print(f"         ! {b}")
+    return 0
+
+
+def cmd_mcp(args: argparse.Namespace) -> int:
+    try:
+        from trunft import mcp_server
+    except ImportError:
+        print("error: MCP support not installed - pip install -e \".[mcp]\"", file=sys.stderr)
+        return 2
+    mcp_server.serve(args.root, args.transport, args.host, args.port)
+    return 0
+
+
+def _filters(p: argparse.ArgumentParser) -> None:
+    p.add_argument("-e", "--env", help="environment (config/environments/<env>.yaml)")
+    p.add_argument("-p", "--platform", action="append", choices=[pl.value for pl in Platform])
+    p.add_argument("--pillar", action="append", help="performance, security, reliability, chaos, ...")
+    p.add_argument("-t", "--type", action="append", help="test type, e.g. load, spike, access_control")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="trunft", description="TruNFT - unified non-functional testing")
+    parser.add_argument("--version", action="version", version=f"trunft {__version__}")
+    parser.add_argument("--root", default=".", help="project root containing config/ (default: cwd)")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    for name, fn, help_ in (("list", cmd_list, "show pillars, test types and platform coverage"),
+                            ("doctor", cmd_doctor, "check external tool availability")):
+        p = sub.add_parser(name, help=help_)
+        p.add_argument("--json", action="store_true")
+        p.set_defaults(fn=fn)
+
+    p = sub.add_parser("init", help="create a TruNFT project (config, k6 workload, chaos, docker)")
+    p.add_argument("path", nargs="?", default=".", help="directory to create the project in (default: cwd)")
+    p.add_argument("--force", action="store_true", help="overwrite existing files")
+    p.set_defaults(fn=cmd_init)
+
+    p = sub.add_parser("setup", help="install missing external tools (winget/brew/npm/pip)")
+    p.add_argument("--tool", action="append", help="only these tools, e.g. --tool k6 --tool adb")
+    p.add_argument("--dry-run", action="store_true", help="show what would be installed")
+    p.set_defaults(fn=cmd_setup)
+
+    p = sub.add_parser("plan", help="preview what a run would execute")
+    _filters(p)
+    p.add_argument("--json", action="store_true")
+    p.set_defaults(fn=cmd_plan)
+
+    p = sub.add_parser("run", help="execute non-functional tests")
+    _filters(p)
+    p.add_argument("-o", "--output", help="report output root (default: reports/)")
+    p.add_argument("--dry-run", action="store_true", help="plan and report without executing")
+    p.set_defaults(fn=cmd_run)
+
+    p = sub.add_parser("reports", help="list recent runs")
+    p.add_argument("-n", "--limit", type=int, default=20)
+    p.add_argument("--json", action="store_true")
+    p.set_defaults(fn=cmd_reports)
+
+    p = sub.add_parser("report", help="show one run's results")
+    p.add_argument("run", help="report folder name (see `trunft reports`)")
+    p.add_argument("--failures", action="store_true", help="only failed/error tests")
+    p.add_argument("--json", action="store_true")
+    p.set_defaults(fn=cmd_report)
+
+    p = sub.add_parser("mcp", help="start the TruNFT MCP server")
+    p.add_argument("--transport", choices=["stdio", "streamable-http"], default="stdio")
+    p.add_argument("--host", default="127.0.0.1")
+    p.add_argument("--port", type=int, default=8765)
+    p.set_defaults(fn=cmd_mcp)
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    try:
+        return args.fn(args)
+    except (ConfigError, ValueError, FileNotFoundError) as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

trunft/core/config.py

@@ -0,0 +1,97 @@
+"""Layered YAML configuration: config/trunft.yaml <- config/environments/<env>.yaml.
+
+String values support ``${VAR}`` and ``${VAR:-default}`` interpolation from the
+process environment so secrets (tokens, passwords) never live in the repo.
+"""
+from __future__ import annotations
+
+import copy
+import os
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+_VAR = re.compile(r"\$\{([A-Za-z_][A-Za-z0-9_]*)(?::-([^}]*))?\}")
+
+
+class ConfigError(Exception):
+    pass
+
+
+def interpolate(value: Any) -> Any:
+    if isinstance(value, str):
+        return _VAR.sub(lambda m: os.environ.get(m.group(1), m.group(2) or ""), value)
+    if isinstance(value, dict):
+        return {k: interpolate(v) for k, v in value.items()}
+    if isinstance(value, list):
+        return [interpolate(v) for v in value]
+    return value
+
+
+# Paths whose dict values are replaced wholesale instead of merged ("*" = any key).
+# k6 scenario options are executor-specific: merging a constant-vus override into a
+# ramping-vus base would leave an invalid hybrid (e.g. `stages` on constant-vus).
+REPLACE_PATHS: tuple[tuple[str, ...], ...] = (("pillars", "performance", "profiles", "*"),)
+
+
+def _replaces(path: tuple[str, ...]) -> bool:
+    return any(len(p) == len(path) and all(a in ("*", b) for a, b in zip(p, path)) for p in REPLACE_PATHS)
+
+
+def deep_merge(base: dict, override: dict, _path: tuple[str, ...] = ()) -> dict:
+    out = copy.deepcopy(base)
+    for key, value in override.items():
+        path = (*_path, str(key))
+        if isinstance(value, dict) and isinstance(out.get(key), dict) and not _replaces(path):
+            out[key] = deep_merge(out[key], value, path)
+        else:
+            out[key] = copy.deepcopy(value)
+    return out
+
+
+@dataclass
+class Config:
+    data: dict[str, Any]
+    environment: str
+    root: Path
+
+    def get(self, dotted: str, default: Any = None) -> Any:
+        node: Any = self.data
+        for part in dotted.split("."):
+            if not isinstance(node, dict) or part not in node:
+                return default
+            node = node[part]
+        return node
+
+    def pillar(self, name: str) -> dict[str, Any]:
+        return self.get(f"pillars.{name}", {}) or {}
+
+    def thresholds(self, pillar: str, test_type: str) -> dict[str, Any]:
+        """``thresholds.<pillar>.default`` overlaid with ``thresholds.<pillar>.<test_type>``."""
+        block = self.get(f"thresholds.{pillar}", {}) or {}
+        return {**(block.get("default") or {}), **(block.get(test_type) or {})}
+
+    def target(self, platform: str) -> dict[str, Any]:
+        return self.get(f"targets.{platform}", {}) or {}
+
+
+def _read_yaml(path: Path) -> dict:
+    try:
+        with path.open(encoding="utf-8") as fh:
+            return yaml.safe_load(fh) or {}
+    except FileNotFoundError as exc:
+        raise ConfigError(f"Config file not found: {path}") from exc
+
+
+def load_config(root: Path, environment: str | None = None) -> Config:
+    root = Path(root).resolve()
+    base = _read_yaml(root / "config" / "trunft.yaml")
+    env = environment or base.get("default_environment", "dev")
+    env_file = root / "config" / "environments" / f"{env}.yaml"
+    merged = deep_merge(base, _read_yaml(env_file)) if env_file.exists() else base
+    if not env_file.exists() and environment:
+        raise ConfigError(f"Unknown environment '{env}' (expected {env_file})")
+    return Config(data=interpolate(merged), environment=env, root=root)

trunft/core/disruption.py

@@ -0,0 +1,96 @@
+"""Shared machinery for reliability and chaos tests.
+
+An ``AvailabilityProbe`` polls a health URL in the background while a fault is
+injected (service killed, failover triggered, latency added...). Afterwards we
+know availability, latency percentiles, longest outage and time to recover.
+"""
+from __future__ import annotations
+
+import threading
+import time
+from dataclasses import dataclass
+
+from .thresholds import percentile
+from .tooling import http_request, run_cmd
+
+
+@dataclass
+class _Sample:
+    t: float
+    ok: bool
+    latency_ms: float
+
+
+class AvailabilityProbe(threading.Thread):
+    def __init__(self, url: str, interval_s: float = 1.0, timeout_s: float = 5.0, headers: dict | None = None):
+        super().__init__(daemon=True)
+        self.url, self.interval_s, self.timeout_s, self.headers = url, interval_s, timeout_s, headers
+        self.samples: list[_Sample] = []
+        self._stop_evt = threading.Event()
+
+    def run(self) -> None:
+        while not self._stop_evt.is_set():
+            r = http_request(self.url, headers=self.headers, timeout=self.timeout_s)
+            self.samples.append(_Sample(time.monotonic(), r.ok, r.latency_ms))
+            self._stop_evt.wait(self.interval_s)
+
+    def stop(self) -> None:
+        self._stop_evt.set()
+        self.join(timeout=self.timeout_s + self.interval_s + 1)
+
+    def metrics(self) -> dict:
+        total = len(self.samples)
+        fails = sum(1 for s in self.samples if not s.ok)
+        ok_lat = [s.latency_ms for s in self.samples if s.ok]
+        longest, start = 0.0, None
+        for s in self.samples:
+            if not s.ok and start is None:
+                start = s.t
+            elif s.ok and start is not None:
+                longest, start = max(longest, s.t - start), None
+        if start is not None and self.samples:
+            longest = max(longest, self.samples[-1].t - start)
+        return {
+            "probes": total,
+            "failed_probes": fails,
+            "availability": round((total - fails) / total, 5) if total else 0.0,
+            "error_rate": round(fails / total, 5) if total else 1.0,
+            "p95_ms": round(percentile(ok_lat, 95) or 0, 1),
+            "max_outage_s": round(longest, 2),
+        }
+
+
+def wait_until_healthy(url: str, timeout_s: float, interval_s: float = 1.0) -> float | None:
+    """Seconds until ``url`` answered healthily, or None on timeout."""
+    start = time.monotonic()
+    while time.monotonic() - start < timeout_s:
+        if http_request(url, timeout=min(5.0, interval_s * 5)).ok:
+            return round(time.monotonic() - start, 2)
+        time.sleep(interval_s)
+    return None
+
+
+def run_disruption(
+    health_url: str,
+    trigger: str,
+    restore: str | None = None,
+    observe_s: float = 60,
+    recovery_timeout_s: float = 300,
+    interval_s: float = 1.0,
+    log_dir=None,
+) -> dict:
+    """Probe ``health_url`` while running ``trigger``; measure impact and recovery."""
+    probe = AvailabilityProbe(health_url, interval_s=interval_s)
+    probe.start()
+    time.sleep(min(5, observe_s / 4))  # baseline before the fault
+    trig = run_cmd(trigger, log_file=log_dir / "trigger.log" if log_dir else None)
+    time.sleep(observe_s)
+    recovery = wait_until_healthy(health_url, recovery_timeout_s, interval_s)
+    probe.stop()
+    if restore:
+        run_cmd(restore, log_file=log_dir / "restore.log" if log_dir else None)
+    metrics = probe.metrics()
+    metrics["trigger_exit_code"] = trig.returncode
+    metrics["recovery_s"] = recovery if recovery is not None else float("inf")
+    metrics["recovered"] = recovery is not None
+    return metrics

trunft/core/models.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+from enum import Enum
+from typing import Any
+
+
+class Platform(str, Enum):
+    WEB = "web"
+    MOBILE_NATIVE = "mobile-native"
+    MOBILE_BROWSER = "mobile-browser"
+    MOBILE_HYBRID = "mobile-hybrid"
+
+    @classmethod
+    def all(cls) -> frozenset["Platform"]:
+        return frozenset(cls)
+
+    @classmethod
+    def mobile_apps(cls) -> frozenset["Platform"]:
+        """Platforms that ship an installable app binary."""
+        return frozenset({cls.MOBILE_NATIVE, cls.MOBILE_HYBRID})
+
+    @classmethod
+    def browser_based(cls) -> frozenset["Platform"]:
+        """Platforms reachable through a URL in a browser."""
+        return frozenset({cls.WEB, cls.MOBILE_BROWSER})
+
+
+class Status(str, Enum):
+    PASSED = "passed"
+    FAILED = "failed"            # ran, but breached a threshold / assertion
+    ERROR = "error"              # could not complete (tool crashed, target down...)
+    SKIPPED = "skipped"          # dry-run, not applicable, or missing tooling
+    NOT_IMPLEMENTED = "not_implemented"  # placeholder awaiting implementation/config
+
+
+@dataclass
+class NFTResult:
+    pillar: str
+    test_type: str
+    platform: Platform
+    status: Status
+    message: str = ""
+    duration_s: float = 0.0
+    metrics: dict[str, Any] = field(default_factory=dict)
+    threshold_breaches: list[str] = field(default_factory=list)
+    artifacts: list[str] = field(default_factory=list)
+
+    @property
+    def is_failure(self) -> bool:
+        return self.status in (Status.FAILED, Status.ERROR)
+
+    def to_dict(self) -> dict[str, Any]:
+        data = asdict(self)
+        data["platform"] = self.platform.value
+        data["status"] = self.status.value
+        return data