brinqz-agent 0.2.0__tar.gz

brinqz_agent-0.2.0/MANIFEST.in

@@ -0,0 +1,10 @@
+include README.md
+include pyproject.toml
+graft src
+prune tests
+prune docs
+prune .github
+prune scripts
+global-exclude *.py[cod]
+global-exclude __pycache__
+global-exclude .DS_Store

brinqz_agent-0.2.0/PKG-INFO

@@ -0,0 +1,199 @@
+Metadata-Version: 2.4
+Name: brinqz-agent
+Version: 0.2.0
+Summary: Secure local execution agent for Brinqz Cloud
+Author: Brinqz
+Maintainer: Brinqz
+License-Expression: LicenseRef-Proprietary
+Project-URL: Homepage, https://brinqz.com
+Project-URL: Documentation, https://github.com/ronnieparalejas/brinqz-agent#readme
+Project-URL: Source, https://github.com/ronnieparalejas/brinqz-agent
+Project-URL: Issues, https://github.com/ronnieparalejas/brinqz-agent/issues
+Project-URL: Support, https://github.com/ronnieparalejas/brinqz-agent/issues
+Project-URL: Brinqz Cloud, https://app.brinqz.com
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: <4,>=3.11
+Description-Content-Type: text/markdown
+Provides-Extra: dev
+Requires-Dist: build>=1.2.2; extra == "dev"
+Requires-Dist: pytest>=8.3; extra == "dev"
+Requires-Dist: twine>=6.1; extra == "dev"
+
+# Brinqz Agent
+
+Brinqz Agent is the local command-line agent that runs approved Robot Framework
+test executions on your machine. Brinqz Cloud is its control plane: the Agent
+pairs with Cloud, receives execution work, runs it through the configured local
+test runtime, and returns approved results and artifacts.
+
+Brinqz Agent is currently a **Public Preview / Alpha** release. It supports
+Windows, macOS, and Linux and requires Python 3.11 or newer (Python 4 is not
+supported).
+
+## Install and set up
+
+Install or upgrade the Agent, then follow its guided setup:
+
+```console
+python -m pip install --upgrade brinqz-agent
+brinqz-agent setup
+```
+
+For an isolated command-line installation, you can use
+[pipx](https://pipx.pypa.io/):
+
+```console
+pipx install brinqz-agent
+brinqz-agent setup
+```
+
+The default control-plane URL is `https://app.brinqz.com`. For local
+development only, you can select a `.test` Cloud origin:
+
+```console
+brinqz-agent setup --cloud-url http://app.brinqz.test
+```
+
+Setup guides you through Cloud pairing and capability choices, prepares an
+isolated Brinqz-managed execution runtime, registers per-user automatic startup,
+starts the Agent, and verifies Cloud health. Robot Framework is always enabled.
+Browser testing is recommended and defaults to Chromium; Firefox and WebKit are
+optional. Parallel execution with Pabot is optional.
+
+It is safe to rerun `brinqz-agent setup`. A healthy matching runtime is reused.
+If repair or an upgrade is needed, setup builds and validates a replacement at
+its final path before selecting it, and retains the previous working runtime
+until activation succeeds.
+
+## Setup choices and managed deployment
+
+Normal users only need the two commands above. Managed deployments and CI can
+inspect advanced options with `brinqz-agent setup --help`. Common examples are:
+
+```console
+# Recommended Chromium and Pabot capabilities
+brinqz-agent setup --yes --recommended
+
+# Explicit browsers and parallel execution
+brinqz-agent setup --yes --browsers chromium,firefox --with-pabot
+
+# Robot-only runtime without background registration
+brinqz-agent setup --yes --robot-only --no-startup
+```
+
+Use `--cloud-url` to select a different approved Cloud origin. Rerun setup with
+`--browsers` or `--with-pabot` to change capabilities. Setup never installs
+project credentials or project secrets.
+
+## Execution runtime
+
+The Agent package environment and execution environment remain separate. Setup
+creates a dedicated virtual environment under the user-scoped Agent data
+directory and never installs Robot Framework, Browser Library, browsers, or
+Pabot globally. It does not change the global `PATH` and does not require
+administrator or root privileges.
+
+Browser setup prefers the official BrowserBatteries distribution, which avoids
+a separate Node.js installation on supported systems. On an unsupported system,
+setup can use an already-installed supported Node.js LTS runtime; it never
+silently installs Node.js or operating-system packages. If Linux browser system
+dependencies are missing, setup reports the requirement without automatically
+using `sudo`.
+
+Use the following command to inspect the Agent configuration, selected runtime,
+and required local capabilities:
+
+```console
+brinqz-agent doctor
+```
+
+Advanced users can keep a compatible external runtime with `brinqz-agent
+runtime use <python-path>`. Setup preserves a valid manually selected runtime;
+use `--managed-runtime` when deliberately switching back to Brinqz management.
+
+## Linux display behavior
+
+Headless Robot and Browser setup works without `DISPLAY`. Headed browser
+execution requires a real logged-in graphical session and a valid `DISPLAY` or
+Wayland environment inherited by the Agent. The Agent does not fabricate display
+variables. A headed request without a display fails with a concise diagnostic.
+Some distributions require browser system libraries installed by an
+administrator; setup explains those requirements and does not elevate itself.
+
+## Background lifecycle
+
+The background registration is per-user: Task Scheduler on Windows, a
+LaunchAgent on macOS, or a systemd user service on Linux.
+
+```console
+brinqz-agent install
+brinqz-agent status
+brinqz-agent start
+brinqz-agent stop
+brinqz-agent restart
+brinqz-agent uninstall
+```
+
+`uninstall` removes background startup registration but preserves pairing,
+managed runtimes, runtime selection, reports, and execution history. Remove the
+user-scoped Brinqz Agent data directory separately only when you deliberately
+want to delete those preserved files. `brinqz-agent run` is
+available as a foreground diagnostic mode.
+
+Managed data locations are:
+
+- Windows: `%LOCALAPPDATA%\Brinqz Agent` (runtime under `runtime`)
+- macOS: `~/Library/Application Support/Brinqz Agent`
+- Linux: `${XDG_DATA_HOME:-~/.local/share}/brinqz-agent`
+
+## Security model
+
+The Agent initiates outbound communication to Brinqz Cloud and does not open
+inbound ports. Pairing establishes a local machine identity through Cloud's
+browser-approval flow, and approved machine credentials are stored in the
+user-scoped Agent configuration.
+
+Project credentials are not entered or configured through Agent setup. An
+execution that requires an unavailable local secret is refused before process
+launch. The Agent executes prepared Robot Framework packages through a fixed
+Robot or Pabot invocation; it does not provide arbitrary remote shell
+execution.
+
+Downloaded packages are authenticated, size and checksum verified, and safely
+extracted. Execution runs in a contained process boundary, and only approved
+report artifacts are returned to Cloud.
+
+## Public Preview limitations
+
+This Alpha release is command-line only. It does not install Python, Node.js,
+Linux operating-system browser dependencies, or project secrets. It does not
+include a GUI or tray application, a native installer, self-update, or
+Runner-local project-secret storage. Interfaces and operational guidance may
+change before a stable release.
+
+## Support
+
+Report problems and request support through the
+[Brinqz Agent issue tracker](https://github.com/ronnieparalejas/brinqz-agent/issues).
+
+## Development
+
+```console
+python -m venv .venv
+# Activate .venv using your shell, then:
+python -m pip install -e ".[dev]"
+python -m pytest
+```
+
+The repository contains additional manual validation plans for maintainers.

brinqz_agent-0.2.0/README.md

@@ -0,0 +1,167 @@
+# Brinqz Agent
+
+Brinqz Agent is the local command-line agent that runs approved Robot Framework
+test executions on your machine. Brinqz Cloud is its control plane: the Agent
+pairs with Cloud, receives execution work, runs it through the configured local
+test runtime, and returns approved results and artifacts.
+
+Brinqz Agent is currently a **Public Preview / Alpha** release. It supports
+Windows, macOS, and Linux and requires Python 3.11 or newer (Python 4 is not
+supported).
+
+## Install and set up
+
+Install or upgrade the Agent, then follow its guided setup:
+
+```console
+python -m pip install --upgrade brinqz-agent
+brinqz-agent setup
+```
+
+For an isolated command-line installation, you can use
+[pipx](https://pipx.pypa.io/):
+
+```console
+pipx install brinqz-agent
+brinqz-agent setup
+```
+
+The default control-plane URL is `https://app.brinqz.com`. For local
+development only, you can select a `.test` Cloud origin:
+
+```console
+brinqz-agent setup --cloud-url http://app.brinqz.test
+```
+
+Setup guides you through Cloud pairing and capability choices, prepares an
+isolated Brinqz-managed execution runtime, registers per-user automatic startup,
+starts the Agent, and verifies Cloud health. Robot Framework is always enabled.
+Browser testing is recommended and defaults to Chromium; Firefox and WebKit are
+optional. Parallel execution with Pabot is optional.
+
+It is safe to rerun `brinqz-agent setup`. A healthy matching runtime is reused.
+If repair or an upgrade is needed, setup builds and validates a replacement at
+its final path before selecting it, and retains the previous working runtime
+until activation succeeds.
+
+## Setup choices and managed deployment
+
+Normal users only need the two commands above. Managed deployments and CI can
+inspect advanced options with `brinqz-agent setup --help`. Common examples are:
+
+```console
+# Recommended Chromium and Pabot capabilities
+brinqz-agent setup --yes --recommended
+
+# Explicit browsers and parallel execution
+brinqz-agent setup --yes --browsers chromium,firefox --with-pabot
+
+# Robot-only runtime without background registration
+brinqz-agent setup --yes --robot-only --no-startup
+```
+
+Use `--cloud-url` to select a different approved Cloud origin. Rerun setup with
+`--browsers` or `--with-pabot` to change capabilities. Setup never installs
+project credentials or project secrets.
+
+## Execution runtime
+
+The Agent package environment and execution environment remain separate. Setup
+creates a dedicated virtual environment under the user-scoped Agent data
+directory and never installs Robot Framework, Browser Library, browsers, or
+Pabot globally. It does not change the global `PATH` and does not require
+administrator or root privileges.
+
+Browser setup prefers the official BrowserBatteries distribution, which avoids
+a separate Node.js installation on supported systems. On an unsupported system,
+setup can use an already-installed supported Node.js LTS runtime; it never
+silently installs Node.js or operating-system packages. If Linux browser system
+dependencies are missing, setup reports the requirement without automatically
+using `sudo`.
+
+Use the following command to inspect the Agent configuration, selected runtime,
+and required local capabilities:
+
+```console
+brinqz-agent doctor
+```
+
+Advanced users can keep a compatible external runtime with `brinqz-agent
+runtime use <python-path>`. Setup preserves a valid manually selected runtime;
+use `--managed-runtime` when deliberately switching back to Brinqz management.
+
+## Linux display behavior
+
+Headless Robot and Browser setup works without `DISPLAY`. Headed browser
+execution requires a real logged-in graphical session and a valid `DISPLAY` or
+Wayland environment inherited by the Agent. The Agent does not fabricate display
+variables. A headed request without a display fails with a concise diagnostic.
+Some distributions require browser system libraries installed by an
+administrator; setup explains those requirements and does not elevate itself.
+
+## Background lifecycle
+
+The background registration is per-user: Task Scheduler on Windows, a
+LaunchAgent on macOS, or a systemd user service on Linux.
+
+```console
+brinqz-agent install
+brinqz-agent status
+brinqz-agent start
+brinqz-agent stop
+brinqz-agent restart
+brinqz-agent uninstall
+```
+
+`uninstall` removes background startup registration but preserves pairing,
+managed runtimes, runtime selection, reports, and execution history. Remove the
+user-scoped Brinqz Agent data directory separately only when you deliberately
+want to delete those preserved files. `brinqz-agent run` is
+available as a foreground diagnostic mode.
+
+Managed data locations are:
+
+- Windows: `%LOCALAPPDATA%\Brinqz Agent` (runtime under `runtime`)
+- macOS: `~/Library/Application Support/Brinqz Agent`
+- Linux: `${XDG_DATA_HOME:-~/.local/share}/brinqz-agent`
+
+## Security model
+
+The Agent initiates outbound communication to Brinqz Cloud and does not open
+inbound ports. Pairing establishes a local machine identity through Cloud's
+browser-approval flow, and approved machine credentials are stored in the
+user-scoped Agent configuration.
+
+Project credentials are not entered or configured through Agent setup. An
+execution that requires an unavailable local secret is refused before process
+launch. The Agent executes prepared Robot Framework packages through a fixed
+Robot or Pabot invocation; it does not provide arbitrary remote shell
+execution.
+
+Downloaded packages are authenticated, size and checksum verified, and safely
+extracted. Execution runs in a contained process boundary, and only approved
+report artifacts are returned to Cloud.
+
+## Public Preview limitations
+
+This Alpha release is command-line only. It does not install Python, Node.js,
+Linux operating-system browser dependencies, or project secrets. It does not
+include a GUI or tray application, a native installer, self-update, or
+Runner-local project-secret storage. Interfaces and operational guidance may
+change before a stable release.
+
+## Support
+
+Report problems and request support through the
+[Brinqz Agent issue tracker](https://github.com/ronnieparalejas/brinqz-agent/issues).
+
+## Development
+
+```console
+python -m venv .venv
+# Activate .venv using your shell, then:
+python -m pip install -e ".[dev]"
+python -m pytest
+```
+
+The repository contains additional manual validation plans for maintainers.

brinqz_agent-0.2.0/pyproject.toml

@@ -0,0 +1,60 @@
+[build-system]
+requires = ["setuptools>=75"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "brinqz-agent"
+dynamic = ["version"]
+description = "Secure local execution agent for Brinqz Cloud"
+readme = "README.md"
+requires-python = ">=3.11,<4"
+license = "LicenseRef-Proprietary"
+authors = [{ name = "Brinqz" }]
+maintainers = [{ name = "Brinqz" }]
+dependencies = []
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Operating System :: MacOS",
+    "Operating System :: Microsoft :: Windows",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Testing",
+]
+
+[project.urls]
+Homepage = "https://brinqz.com"
+Documentation = "https://github.com/ronnieparalejas/brinqz-agent#readme"
+Source = "https://github.com/ronnieparalejas/brinqz-agent"
+Issues = "https://github.com/ronnieparalejas/brinqz-agent/issues"
+Support = "https://github.com/ronnieparalejas/brinqz-agent/issues"
+"Brinqz Cloud" = "https://app.brinqz.com"
+
+[project.optional-dependencies]
+dev = [
+    "build>=1.2.2",
+    "pytest>=8.3",
+    "twine>=6.1",
+]
+
+[project.scripts]
+brinqz-agent = "brinqz_agent.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.dynamic]
+version = { attr = "brinqz_agent.version.__version__" }
+
+[tool.setuptools.package-data]
+brinqz_agent = ["listeners/brinqz_robot_listener.py"]
+
+[tool.pytest.ini_options]
+addopts = "-ra"
+testpaths = ["tests"]
+pythonpath = ["src"]

brinqz_agent-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

brinqz_agent-0.2.0/src/brinqz_agent/__init__.py

@@ -0,0 +1,6 @@
+"""Brinqz Agent CLI foundation."""
+
+from brinqz_agent.version import __version__
+
+__all__ = ["__version__"]
+

brinqz_agent-0.2.0/src/brinqz_agent/__main__.py

@@ -0,0 +1,4 @@
+from brinqz_agent.cli import main
+
+raise SystemExit(main())
+

brinqz_agent-0.2.0/src/brinqz_agent/artifacts.py

@@ -0,0 +1,173 @@
+"""Allow-listed Robot result collection for the existing Cloud contract."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from xml.etree import ElementTree
+import hashlib
+import json
+import os
+import re
+
+from brinqz_agent.cloud import ArtifactUpload
+
+MAX_SCREENSHOTS = 25
+MAX_SCREENSHOT_BYTES = 10 * 1024 * 1024
+MAX_OUTPUT_XML_BYTES = 16 * 1024 * 1024
+MAX_REPORT_SUMMARY_BYTES = 2 * 1024 * 1024
+
+
+class ArtifactCollectionError(RuntimeError):
+    pass
+
+
+def collect_cloud_artifacts(output_directory: Path) -> tuple[ArtifactUpload, ...]:
+    if not output_directory.is_dir() or output_directory.is_symlink():
+        return ()
+    root = output_directory.resolve()
+    artifacts = list(_screenshots(root))
+    output_xml = root / "output.xml"
+    if _safe_regular_file(output_xml, root):
+        size = output_xml.stat().st_size
+        if 0 < size <= MAX_OUTPUT_XML_BYTES:
+            sanitized = _sanitized_output_xml(output_xml)
+            artifacts.append(
+                _artifact(
+                    sanitized,
+                    "artifact-robot_output-output-xml",
+                    "robot_output",
+                    "output.xml",
+                    "application/xml",
+                )
+            )
+    return tuple(artifacts)
+
+
+def report_summary_path(output_directory: Path) -> Path | None:
+    if not output_directory.is_dir() or output_directory.is_symlink():
+        return None
+    root = output_directory.resolve()
+    candidate = root / "report-summary.json"
+    if not _safe_regular_file(candidate, root):
+        return None
+    size = candidate.stat().st_size
+    if size <= 0 or size > MAX_REPORT_SUMMARY_BYTES:
+        return None
+    try:
+        payload = json.loads(candidate.read_text(encoding="utf-8"))
+    except (OSError, UnicodeError, json.JSONDecodeError):
+        return None
+    return candidate if isinstance(payload, dict) else None
+
+
+def _screenshots(root: Path):
+    screenshot_root = root / "browser" / "screenshot"
+    if not screenshot_root.is_dir() or screenshot_root.is_symlink():
+        return ()
+    found: list[ArtifactUpload] = []
+    for candidate in sorted(screenshot_root.rglob("*")):
+        if len(found) >= MAX_SCREENSHOTS:
+            break
+        if not _safe_regular_file(candidate, root):
+            continue
+        size = candidate.stat().st_size
+        content_type = _screenshot_type(candidate)
+        if not content_type or size <= 0 or size > MAX_SCREENSHOT_BYTES:
+            continue
+        if not _screenshot_magic(candidate, content_type):
+            continue
+        relative = candidate.resolve().relative_to(root).as_posix()
+        if not relative.startswith("browser/screenshot/"):
+            continue
+        found.append(
+            _artifact(
+                candidate,
+                _stable_artifact_id(relative, "screenshot"),
+                "screenshot",
+                relative,
+                content_type,
+            )
+        )
+    return tuple(found)
+
+
+def _safe_regular_file(path: Path, root: Path) -> bool:
+    try:
+        if not path.is_file() or path.is_symlink():
+            return False
+        resolved = path.resolve()
+        return os.path.commonpath((str(root), str(resolved))) == str(root)
+    except (OSError, ValueError):
+        return False
+
+
+def _sanitized_output_xml(source: Path) -> Path:
+    try:
+        content = source.read_text(encoding="utf-8")
+        if re.search(r"(?i)<!DOCTYPE|<!ENTITY", content):
+            raise ArtifactCollectionError("Robot output.xml contains a forbidden declaration.")
+        root = ElementTree.fromstring(content)
+    except (OSError, UnicodeError, ElementTree.ParseError) as error:
+        raise ArtifactCollectionError("Robot output.xml is invalid.") from error
+    if root.tag != "robot":
+        raise ArtifactCollectionError("Robot output.xml has an unexpected root element.")
+    sanitized = re.sub(
+        r"(?i)\b(password|token|secret|api[_-]?key|login_password)\b(\s*[:=]\s*)([^\s<]+)",
+        r"\1\2[redacted]",
+        content,
+    )
+    destination = source.with_name(".brinqz-cloud-output.xml")
+    destination.write_text(sanitized, encoding="utf-8")
+    return destination
+
+
+def _artifact(
+    path: Path,
+    artifact_id: str,
+    artifact_type: str,
+    relative_path: str,
+    content_type: str,
+) -> ArtifactUpload:
+    size = path.stat().st_size
+    digest = hashlib.sha256()
+    with path.open("rb") as stream:
+        while chunk := stream.read(128 * 1024):
+            digest.update(chunk)
+    return ArtifactUpload(
+        artifact_id,
+        artifact_type,
+        relative_path,
+        content_type,
+        size,
+        digest.hexdigest(),
+        path,
+    )
+
+
+def _screenshot_type(path: Path) -> str | None:
+    return {
+        ".png": "image/png",
+        ".jpg": "image/jpeg",
+        ".jpeg": "image/jpeg",
+        ".webp": "image/webp",
+    }.get(path.suffix.lower())
+
+
+def _screenshot_magic(path: Path, content_type: str) -> bool:
+    with path.open("rb") as stream:
+        header = stream.read(12)
+    if content_type == "image/png":
+        return header.startswith(b"\x89PNG\r\n\x1a\n")
+    if content_type == "image/jpeg":
+        return header.startswith(b"\xff\xd8\xff")
+    return len(header) >= 12 and header[:4] == b"RIFF" and header[8:12] == b"WEBP"
+
+
+def _stable_artifact_id(relative_path: str, kind: str) -> str:
+    value = f"artifact-{kind}-"
+    for character in relative_path:
+        if character.isascii() and character.isalnum():
+            value += character.lower()
+        elif character in "/.-_" and not value.endswith("-"):
+            value += "-"
+    return value.rstrip("-")