node-mantis 0.1.0a1__py3-none-win_amd64.whl

node_mantis-0.1.0a1.dist-info/METADATA

@@ -0,0 +1,44 @@
+Metadata-Version: 2.4
+Name: node-mantis
+Version: 0.1.0a1
+Summary: NodeMantis Python SDK and source-free install smoke CLI
+Author: NodeMantis
+License-Expression: LicenseRef-NodeMantis-Proprietary
+Project-URL: Homepage, https://github.com/Node-Mantis/CleanSlate#readme
+Project-URL: Repository, https://github.com/Node-Mantis/CleanSlate
+Project-URL: Issues, https://github.com/Node-Mantis/CleanSlate/issues
+Keywords: browser,automation,playwright,node-mantis,nodemantis
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+Provides-Extra: browser
+Requires-Dist: playwright>=1.59.1; extra == "browser"
+Dynamic: license-file
+
+# NodeMantis Python
+
+Alpha Python SDK and source-free smoke CLI for NodeMantis.
+
+Customer install:
+
+```bash
+pip install node-mantis
+pip install "node-mantis[browser]"
+python -m nodemantis configure --api-key "$NODEMANTIS_API_KEY"
+python -m nodemantis smoke
+```
+
+`node-mantis[browser]` installs Playwright for SDK-managed browser checks and
+smoke tests.
+
+Supported alpha platforms: Linux x64, Windows x64, macOS x64, and macOS arm64.
+
+This package is proprietary alpha software. Use is governed by `LICENSE.txt`
+and applicable NodeMantis terms.

node_mantis-0.1.0a1.dist-info/RECORD

@@ -0,0 +1,16 @@
+node_mantis-0.1.0a1.dist-info/licenses/LICENSE.txt,sha256=obNmXb8HRVRK9NB5-M-zQLEsxypU5FBcBUzOChWKpbo,920
+nodemantis/__init__.py,sha256=bxihFLQm85R93Co76qmYt2d6NOLjwQf5WZS5g3zSURI,469
+nodemantis/__main__.py,sha256=0iDYjdmiXNBinFF23WUyotsdpA6wFKjoB5aw3esTSRg,83
+nodemantis/browser.py,sha256=yCwczEnDe0t7T61w-TrWnwSs-b0qc15Pv8QsT-9zUXw,2485
+nodemantis/cli.py,sha256=gnBxDS3rv_LoZLMMrEhUdpdUkr22W6wHDmz2LEA1U0w,5960
+nodemantis/config.py,sha256=bsM3FvVoMP1kK8qxK0T6ET2rS-hn5fbQRvFioKHs2Rw,4493
+nodemantis/py.typed,sha256=frcCV1k9oG9oKj3dpUqdJg1PxRT2RSN_XKdLCPjaYaY,2
+nodemantis/runtime.py,sha256=MCkAXvIP4j0NREYp7df3DUfok5W9Q0lSNlu8jv9rTCo,2239
+nodemantis/runtime_broker.py,sha256=EdqAdkKwqXRrlMwHiGUwPmTyFFjhv_rVGMMtcv7bKqU,588
+nodemantis/smoke.py,sha256=B6HcKWYjhBJFcoHTSF4HRQZNowhwjxE6mmiI6V7JHow,5049
+nodemantis/fixtures/smoke.html,sha256=ulix-qaiBCHqGpMJRI9OmANt01lhEMFDASgs-2O1kz0,690
+node_mantis-0.1.0a1.dist-info/METADATA,sha256=6WV_HBommm5C6MmGZnzKsijyxEPxAhGa6LsLWKQNR5w,1575
+node_mantis-0.1.0a1.dist-info/WHEEL,sha256=hVx9elvUDfBjRmbl8JwIcXXikst35RZTZK9nspfI_28,98
+node_mantis-0.1.0a1.dist-info/entry_points.txt,sha256=iB3hkGF-CFZaPeeUadgxrljZqJV2FRCIClWIJGEK-hg,51
+node_mantis-0.1.0a1.dist-info/top_level.txt,sha256=9kaSA3eSBIApvJUTG4Ni6h42DcfJebMhccQj_tS9Bu4,11
+node_mantis-0.1.0a1.dist-info/RECORD,,

node_mantis-0.1.0a1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: false
+Tag: py3-none-win_amd64
+

node_mantis-0.1.0a1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+nodemantis = nodemantis.cli:main

node_mantis-0.1.0a1.dist-info/licenses/LICENSE.txt

@@ -0,0 +1,18 @@
+NodeMantis Alpha Proprietary License
+
+Copyright (c) NodeMantis. All rights reserved.
+
+This alpha package is proprietary software. You may install and use it only to
+evaluate or access NodeMantis services under an active NodeMantis account,
+agreement, or written authorization from NodeMantis.
+
+You may not copy, redistribute, sublicense, sell, rent, lease, host for third
+parties, or provide this software as a managed service without prior written
+permission from NodeMantis. You may not reverse engineer, decompile, disassemble,
+or attempt to derive source code from this software except to the extent that
+applicable law prohibits this restriction.
+
+This alpha software is provided "as is" without warranties of any kind. It may
+change, break compatibility, or be withdrawn at any time. To the maximum extent
+permitted by law, NodeMantis is not liable for damages arising from use of this
+software.

node_mantis-0.1.0a1.dist-info/top_level.txt

@@ -0,0 +1 @@
+nodemantis

nodemantis/__init__.py

@@ -0,0 +1,17 @@
+"""NodeMantis Python SDK install and smoke-test helpers."""
+
+from .config import DEFAULT_BACKEND_URL, ResolvedConfig, resolve_config
+from .runtime import UnsupportedPlatformError, runtime_platform_info
+from .smoke import SmokeResult, run_smoke
+
+__all__ = [
+    "DEFAULT_BACKEND_URL",
+    "ResolvedConfig",
+    "SmokeResult",
+    "UnsupportedPlatformError",
+    "resolve_config",
+    "run_smoke",
+    "runtime_platform_info",
+]
+
+__version__ = "0.1.0a1"

nodemantis/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

nodemantis/browser.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+import subprocess
+import sys
+from dataclasses import dataclass
+from typing import Literal
+
+BrowserName = Literal["chrome", "chromium"]
+
+
+@dataclass(frozen=True)
+class BrowserCheckResult:
+    browser: BrowserName
+    available: bool
+    error: str | None = None
+
+
+def normalize_browser(value: str | None) -> BrowserName:
+    if value in (None, "", "chrome"):
+        return "chrome"
+    if value == "chromium":
+        return "chromium"
+    raise ValueError(f'Unsupported browser "{value}". Use "chrome" or "chromium".')
+
+
+def check_browser(browser: BrowserName = "chrome") -> BrowserCheckResult:
+    try:
+        from playwright.sync_api import sync_playwright
+    except ImportError as exc:
+        return BrowserCheckResult(
+            browser=browser,
+            available=False,
+            error=f"Playwright is not installed: {exc}",
+        )
+
+    try:
+        with sync_playwright() as p:
+            launch_options = {"headless": True}
+            if browser == "chrome":
+                launch_options["channel"] = "chrome"
+            launched = p.chromium.launch(**launch_options)
+            launched.close()
+        return BrowserCheckResult(browser=browser, available=True)
+    except Exception as exc:  # noqa: BLE001 - surfaced as a user-facing diagnostic.
+        return BrowserCheckResult(browser=browser, available=False, error=str(exc))
+
+
+def install_browser(browser: BrowserName = "chrome") -> None:
+    subprocess.check_call([sys.executable, "-m", "playwright", "install", browser])
+
+
+def browser_install_command(browser: BrowserName = "chrome") -> str:
+    if browser == "chrome":
+        return "python -m nodemantis install-browser"
+    return "python -m nodemantis install-browser --browser chromium"
+
+
+def missing_browser_message(browser: BrowserName = "chrome", details: str | None = None) -> str:
+    label = "Google Chrome" if browser == "chrome" else "Chromium"
+    lines = [
+        f"{label} is not installed or is not launchable by Playwright.",
+        "Install Playwright browser support with: pip install 'node-mantis[browser]'",
+        f"Install the browser with: {browser_install_command(browser)}",
+    ]
+    if browser == "chrome":
+        lines.append("For CI fallback, run smoke with --browser chromium after installing Chromium.")
+    if details:
+        lines.extend(["", "Playwright error:", details])
+    return "\n".join(lines)

nodemantis/cli.py

@@ -0,0 +1,147 @@
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from .browser import check_browser, install_browser, missing_browser_message, normalize_browser
+from .config import DEFAULT_BACKEND_URL, ConfigFile, mask_secret, read_config_file, resolve_config, write_config_file
+from .runtime import broker_hello, runtime_platform_info
+from .smoke import run_smoke
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="nodemantis")
+    parser.add_argument("--version", action="version", version="nodemantis 0.1.0a1")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    configure = subparsers.add_parser("configure", help="write NodeMantis API credentials")
+    configure.add_argument("--api-key")
+    configure.add_argument("--auth-token")
+    configure.add_argument("--backend-url", default=DEFAULT_BACKEND_URL)
+    configure.add_argument("--config")
+    configure.set_defaults(func=_configure)
+
+    doctor = subparsers.add_parser("doctor", help="check config, platform runtime, and browser availability")
+    doctor.add_argument("--api-key")
+    doctor.add_argument("--backend-url")
+    doctor.add_argument("--browser", default="chrome")
+    doctor.add_argument("--json", action="store_true")
+    doctor.set_defaults(func=_doctor)
+
+    install = subparsers.add_parser("install-browser", help="install Google Chrome or Chromium")
+    install.add_argument("--browser", default="chrome")
+    install.set_defaults(func=_install_browser)
+
+    smoke = subparsers.add_parser("smoke", help="run a source-free customer install smoke test")
+    smoke.add_argument("--api-key")
+    smoke.add_argument("--backend-url")
+    smoke.add_argument("--browser", default="chrome")
+    smoke.add_argument("--install-browser", action="store_true")
+    smoke.add_argument("--headed", action="store_true")
+    smoke.add_argument("--skip-backend", action="store_true", help="skip backend probe; intended for package tests only")
+    smoke.set_defaults(func=_smoke)
+
+    args = parser.parse_args(argv)
+    try:
+        return int(args.func(args) or 0)
+    except Exception as exc:  # noqa: BLE001 - CLI boundary.
+        print(str(exc), file=sys.stderr)
+        return 1
+
+
+def _configure(args: argparse.Namespace) -> int:
+    existing = read_config_file(args.config)
+    credential = args.api_key or args.auth_token
+    if not credential and sys.stdin.isatty():
+        credential = input("NodeMantis API key: ").strip()
+
+    if args.api_key:
+        next_config = ConfigFile(api_key=args.api_key, auth_token=None, backend_url=args.backend_url or existing.backend_url)
+    elif args.auth_token:
+        next_config = ConfigFile(api_key=None, auth_token=args.auth_token, backend_url=args.backend_url or existing.backend_url)
+    elif credential:
+        next_config = ConfigFile(api_key=credential, auth_token=None, backend_url=args.backend_url or existing.backend_url)
+    else:
+        next_config = ConfigFile(
+            api_key=existing.api_key,
+            auth_token=existing.auth_token,
+            backend_url=args.backend_url or existing.backend_url,
+        )
+
+    path = write_config_file(next_config, args.config)
+    resolved = resolve_config(config_path=path)
+    print(f"Wrote NodeMantis config: {resolved.config_path}")
+    print(f"Backend: {resolved.backend_url}")
+    print(f"API key: {mask_secret(resolved.api_key)}")
+    return 0
+
+
+def _doctor(args: argparse.Namespace) -> int:
+    browser = normalize_browser(args.browser)
+    resolved = resolve_config(api_key=args.api_key, backend_url=args.backend_url)
+    report: dict[str, object] = {
+        "configPath": str(resolved.config_path),
+        "backendUrl": resolved.backend_url,
+        "backendUrlSource": resolved.backend_url_source,
+        "apiKeySource": resolved.api_key_source or "missing",
+        "apiKey": mask_secret(resolved.api_key),
+    }
+
+    try:
+        report["platform"] = runtime_platform_info().__dict__
+        report["runtime"] = broker_hello()
+    except Exception as exc:  # noqa: BLE001
+        report["runtimeError"] = str(exc)
+
+    browser_check = check_browser(browser)
+    report["browser"] = {
+        "name": browser,
+        "available": browser_check.available,
+        "error": browser_check.error,
+    }
+
+    if args.json:
+        print(json.dumps(report, indent=2))
+        return 0
+
+    print(f"Config: {report['configPath']}")
+    print(f"Backend: {resolved.backend_url} ({resolved.backend_url_source})")
+    source = f" ({resolved.api_key_source})" if resolved.api_key_source else ""
+    print(f"API key: {mask_secret(resolved.api_key)}{source}")
+    if "runtimeError" in report:
+        print(f"Runtime: failed - {report['runtimeError']}")
+    else:
+        print(f"Runtime: ok ({report['platform']})")
+    print(f"Browser: {'ok' if browser_check.available else 'missing'} ({browser})")
+    if not browser_check.available:
+        print(missing_browser_message(browser))
+    return 0
+
+
+def _install_browser(args: argparse.Namespace) -> int:
+    browser = normalize_browser(args.browser)
+    install_browser(browser)
+    print(f"Installed {'Google Chrome' if browser == 'chrome' else 'Chromium'} for NodeMantis.")
+    return 0
+
+
+def _smoke(args: argparse.Namespace) -> int:
+    result = run_smoke(
+        api_key=args.api_key,
+        backend_url=args.backend_url,
+        browser=args.browser,
+        install_browser=args.install_browser,
+        headless=not args.headed,
+        skip_backend=args.skip_backend,
+    )
+    print("NodeMantis smoke passed.")
+    print(f"Backend: {result.backend_url if result.backend_checked else 'skipped'}")
+    print(f"Runtime: {result.runtime_platform}")
+    print(f"Browser: {result.browser}")
+    print(f"Assertion: {result.assertion}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

nodemantis/config.py

@@ -0,0 +1,135 @@
+from __future__ import annotations
+
+import json
+import os
+import platform
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Mapping, Optional
+
+DEFAULT_BACKEND_URL = "https://api.nodemantis.com"
+
+
+@dataclass(frozen=True)
+class ConfigFile:
+    api_key: Optional[str] = None
+    auth_token: Optional[str] = None
+    backend_url: Optional[str] = None
+
+
+@dataclass(frozen=True)
+class ResolvedConfig:
+    api_key: Optional[str]
+    api_key_source: Optional[str]
+    backend_url: str
+    backend_url_source: str
+    config_path: Path
+    file_config: ConfigFile
+
+
+def get_config_path(env: Mapping[str, str] | None = None) -> Path:
+    env = os.environ if env is None else env
+    override = _clean(env.get("NODEMANTIS_CONFIG_FILE"))
+    if override:
+        return Path(override)
+
+    home = Path.home()
+    system = platform.system().lower()
+    if system == "windows":
+        return Path(env.get("APPDATA", home / "AppData" / "Roaming")) / "nodemantis" / "config.json"
+    if system == "darwin":
+        return home / "Library" / "Application Support" / "nodemantis" / "config.json"
+    return Path(env.get("XDG_CONFIG_HOME", home / ".config")) / "nodemantis" / "config.json"
+
+
+def read_config_file(config_path: Path | str | None = None) -> ConfigFile:
+    path = Path(config_path) if config_path else get_config_path()
+    if not path.exists():
+        return ConfigFile()
+
+    data = json.loads(path.read_text(encoding="utf-8") or "{}")
+    return ConfigFile(
+        api_key=_clean(data.get("apiKey") or data.get("api_key")),
+        auth_token=_clean(data.get("authToken") or data.get("auth_token")),
+        backend_url=_clean(data.get("backendUrl") or data.get("backend_url")),
+    )
+
+
+def write_config_file(config: ConfigFile, config_path: Path | str | None = None) -> Path:
+    path = Path(config_path) if config_path else get_config_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    data = {
+        "apiKey": config.api_key,
+        "authToken": config.auth_token,
+        "backendUrl": config.backend_url,
+    }
+    path.write_text(json.dumps({k: v for k, v in data.items() if v}, indent=2) + "\n", encoding="utf-8")
+    try:
+        path.chmod(0o600)
+    except OSError:
+        pass
+    return path
+
+
+def resolve_config(
+    *,
+    api_key: str | None = None,
+    backend_url: str | None = None,
+    config_path: Path | str | None = None,
+    env: Mapping[str, str] | None = None,
+) -> ResolvedConfig:
+    env = os.environ if env is None else env
+    path = Path(config_path) if config_path else get_config_path(env)
+    file_config = read_config_file(path)
+
+    explicit_key = _clean(api_key)
+    env_api_key = _clean(env.get("NODEMANTIS_API_KEY"))
+    env_auth_token = _clean(env.get("NODEMANTIS_AUTH_TOKEN"))
+    file_key = _clean(file_config.api_key) or _clean(file_config.auth_token)
+
+    if explicit_key:
+        resolved_key, key_source = explicit_key, "explicit"
+    elif env_api_key:
+        resolved_key, key_source = env_api_key, "NODEMANTIS_API_KEY"
+    elif env_auth_token:
+        resolved_key, key_source = env_auth_token, "NODEMANTIS_AUTH_TOKEN"
+    elif file_key:
+        resolved_key, key_source = file_key, "config"
+    else:
+        resolved_key, key_source = None, None
+
+    explicit_backend = _clean(backend_url)
+    env_backend = _clean(env.get("NODEMANTIS_BACKEND_URL"))
+    file_backend = _clean(file_config.backend_url)
+    if explicit_backend:
+        resolved_backend, backend_source = explicit_backend, "explicit"
+    elif env_backend:
+        resolved_backend, backend_source = env_backend, "NODEMANTIS_BACKEND_URL"
+    elif file_backend:
+        resolved_backend, backend_source = file_backend, "config"
+    else:
+        resolved_backend, backend_source = DEFAULT_BACKEND_URL, "default"
+
+    return ResolvedConfig(
+        api_key=resolved_key,
+        api_key_source=key_source,
+        backend_url=resolved_backend,
+        backend_url_source=backend_source,
+        config_path=path,
+        file_config=file_config,
+    )
+
+
+def mask_secret(secret: str | None) -> str:
+    if not secret:
+        return "not configured"
+    if len(secret) <= 8:
+        return "configured"
+    return f"{secret[:4]}...{secret[-4:]}"
+
+
+def _clean(value: object) -> Optional[str]:
+    if not isinstance(value, str):
+        return None
+    stripped = value.strip()
+    return stripped or None

nodemantis/fixtures/smoke.html

@@ -0,0 +1,22 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <title>NodeMantis Smoke Fixture</title>
+    <style>
+      body { font-family: system-ui, sans-serif; margin: 40px; }
+      button { font: inherit; padding: 8px 12px; }
+      #status { margin-top: 16px; font-weight: 700; }
+    </style>
+  </head>
+  <body>
+    <h1>NodeMantis Smoke Fixture</h1>
+    <button id="complete" type="button">Complete fixture</button>
+    <p id="status">waiting</p>
+    <script>
+      document.getElementById("complete").addEventListener("click", () => {
+        document.getElementById("status").textContent = "fixture success";
+      });
+    </script>
+  </body>
+</html>

nodemantis/py.typed

@@ -0,0 +1 @@
+

nodemantis/runtime.py

@@ -0,0 +1,75 @@
+from __future__ import annotations
+
+import json
+import os
+import platform
+import subprocess
+import sys
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class RuntimePlatformInfo:
+    os_name: str
+    arch: str
+    tag: str
+
+
+SUPPORTED_PLATFORMS = {
+    ("linux", "x64"): "linux-x64",
+    ("windows", "x64"): "win32-x64",
+    ("darwin", "x64"): "darwin-x64",
+    ("darwin", "arm64"): "darwin-arm64",
+}
+
+
+class UnsupportedPlatformError(RuntimeError):
+    def __init__(self, os_name: str, arch: str) -> None:
+        super().__init__(
+            "NodeMantis v1 supports Linux x64, Windows x64, macOS x64, and macOS arm64. "
+            f"Current platform is {os_name}/{arch}."
+        )
+        self.os_name = os_name
+        self.arch = arch
+
+
+def runtime_platform_info(
+    os_name: str | None = None,
+    machine: str | None = None,
+) -> RuntimePlatformInfo:
+    normalized_os = _normalize_os(os_name or platform.system())
+    normalized_arch = _normalize_arch(machine or platform.machine())
+    tag = SUPPORTED_PLATFORMS.get((normalized_os, normalized_arch))
+    if not tag:
+        raise UnsupportedPlatformError(normalized_os, normalized_arch)
+    return RuntimePlatformInfo(os_name=normalized_os, arch=normalized_arch, tag=tag)
+
+
+def broker_hello() -> dict[str, str]:
+    runtime_platform_info()
+    runtime_path = os.environ.get("NODEMANTIS_RUNTIME_PATH")
+    command = [runtime_path, "hello"] if runtime_path else [sys.executable, "-m", "nodemantis.runtime_broker", "hello"]
+    result = subprocess.run(command, check=True, capture_output=True, text=True)
+    return json.loads(result.stdout)
+
+
+def _normalize_os(value: str) -> str:
+    lowered = value.lower()
+    if lowered.startswith("msys") or lowered.startswith("mingw"):
+        return "windows"
+    if lowered == "windows":
+        return "windows"
+    if lowered == "darwin":
+        return "darwin"
+    if lowered == "linux":
+        return "linux"
+    return lowered
+
+
+def _normalize_arch(value: str) -> str:
+    lowered = value.lower()
+    if lowered in {"x86_64", "amd64", "x64"}:
+        return "x64"
+    if lowered in {"arm64", "aarch64"}:
+        return "arm64"
+    return lowered

nodemantis/runtime_broker.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+import json
+import sys
+
+from .runtime import runtime_platform_info
+
+
+def main(argv: list[str] | None = None) -> int:
+    argv = argv or sys.argv[1:]
+    if argv != ["hello"]:
+        print("usage: python -m nodemantis.runtime_broker hello", file=sys.stderr)
+        return 2
+
+    info = runtime_platform_info()
+    print(json.dumps({
+        "runtime": "nodemantis-python-broker",
+        "runtimeVersion": "0.1.0a1",
+        "platform": info.tag,
+    }))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

nodemantis/smoke.py

@@ -0,0 +1,148 @@
+from __future__ import annotations
+
+import base64
+import os
+import sys
+from dataclasses import dataclass
+from importlib import resources
+from typing import Optional
+from urllib.error import HTTPError
+from urllib.request import Request, urlopen
+from urllib.parse import urljoin
+
+from .browser import (
+    BrowserName,
+    browser_install_command,
+    check_browser,
+    install_browser as install_browser_package,
+    missing_browser_message,
+    normalize_browser,
+)
+from .config import resolve_config
+from .runtime import broker_hello, runtime_platform_info
+
+
+@dataclass(frozen=True)
+class SmokeResult:
+    ok: bool
+    backend_url: str
+    backend_checked: bool
+    browser: BrowserName
+    runtime_platform: str
+    assertion: str
+
+
+def run_smoke(
+    *,
+    api_key: str | None = None,
+    backend_url: str | None = None,
+    browser: str | None = "chrome",
+    install_browser: bool = False,
+    headless: bool = True,
+    skip_backend: bool = False,
+    timeout_seconds: int = 15,
+) -> SmokeResult:
+    browser_name = normalize_browser(browser)
+    config = resolve_config(api_key=api_key, backend_url=backend_url)
+    platform_info = runtime_platform_info()
+
+    if not config.api_key and not skip_backend:
+        raise RuntimeError(
+            "NodeMantis API key is not configured.\n"
+            "Set NODEMANTIS_API_KEY, NODEMANTIS_AUTH_TOKEN, or run: "
+            "python -m nodemantis configure --api-key <key>"
+        )
+
+    browser_check = check_browser(browser_name)
+    if not browser_check.available:
+        if install_browser:
+            install_browser_package(browser_name)
+            browser_check = check_browser(browser_name)
+        elif _is_interactive():
+            answer = input(
+                f"{'Google Chrome' if browser_name == 'chrome' else 'Chromium'} is missing. "
+                f"Install with {browser_install_command(browser_name)} now? [y/N] "
+            )
+            if answer.strip().lower() in {"y", "yes"}:
+                install_browser_package(browser_name)
+                browser_check = check_browser(browser_name)
+
+    if not browser_check.available:
+        raise RuntimeError(missing_browser_message(browser_name, browser_check.error))
+
+    broker_hello()
+
+    if not skip_backend:
+        _verify_backend_usage(
+            api_key=config.api_key or "",
+            backend_url=config.backend_url,
+            timeout_seconds=timeout_seconds,
+        )
+
+    _verify_fixture(browser_name, headless=headless)
+
+    return SmokeResult(
+        ok=True,
+        backend_url=config.backend_url,
+        backend_checked=not skip_backend,
+        browser=browser_name,
+        runtime_platform=platform_info.tag,
+        assertion="local fixture button changed status to fixture success",
+    )
+
+
+def _verify_backend_usage(
+    *,
+    api_key: str,
+    backend_url: str,
+    timeout_seconds: int,
+) -> None:
+    url = urljoin(backend_url.rstrip("/") + "/", "v1/usage")
+    request = Request(
+        url,
+        method="GET",
+        headers={
+            "authorization": f"Bearer {api_key}",
+        },
+    )
+
+    try:
+        with urlopen(request, timeout=timeout_seconds) as response:  # noqa: S310 - user-configured backend URL.
+            if response.status < 200 or response.status >= 300:
+                raise RuntimeError(f"NodeMantis backend usage check failed: HTTP {response.status}")
+    except HTTPError as exc:
+        body = exc.read(500).decode("utf-8", errors="replace")
+        raise RuntimeError(
+            f"NodeMantis backend usage check failed: HTTP {exc.code}{chr(10) + body if body else ''}"
+        ) from exc
+
+
+def _verify_fixture(browser: BrowserName, *, headless: bool) -> None:
+    try:
+        from playwright.sync_api import sync_playwright
+    except ImportError as exc:
+        raise RuntimeError(
+            "Playwright is required for Python smoke. Install with: pip install 'node-mantis[browser]'"
+        ) from exc
+
+    html = resources.files("nodemantis.fixtures").joinpath("smoke.html").read_text(encoding="utf-8")
+    data_url = "data:text/html;base64," + base64.b64encode(html.encode("utf-8")).decode("ascii")
+
+    with sync_playwright() as p:
+        launch_options = {"headless": headless}
+        if browser == "chrome":
+            launch_options["channel"] = "chrome"
+        launched = p.chromium.launch(**launch_options)
+        try:
+            page = launched.new_page()
+            page.goto(data_url, wait_until="domcontentloaded")
+            page.locator("#complete").click()
+            status = page.locator("#status").inner_text(timeout=5000).strip()
+            if status != "fixture success":
+                raise RuntimeError(f'Smoke fixture assertion failed: expected "fixture success", got "{status}"')
+        finally:
+            launched.close()
+
+
+def _is_interactive() -> bool:
+    return sys.stdin.isatty() and sys.stdout.isatty() and os.environ.get("CI") != "true"