browserget 1.0.1__tar.gz

browserget-1.0.1/.gitignore

@@ -0,0 +1,31 @@
+ref/
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.tox/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+htmlcov/
+.coverage
+.coverage.*
+venv/
+.venv/
+.env
+.venv-dev/
+
+# Additional ignores
+coverage.xml
+*.so
+.idea/
+.vscode/
+*.swp
+*.swo
+site/
+spike.py
+errors.txt
+out.yml

browserget-1.0.1/CHANGELOG.md

@@ -0,0 +1,54 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [1.0.1] - 2026-08-17
+
+### Fixed
+
+- Corrected PyPI publish action reference in release workflow
+
+## [1.0.0] - 2026-08-17
+
+### Added
+
+- Project scaffolding: directory structure, community files, CI workflows
+- `pyproject.toml` with `dev` and `docs` optional dependencies
+- GitHub Actions: CI (lint + matrix test), coverage, docs deploy
+- Issue templates (bug report, feature request) and PR template
+- Dependabot configuration for pip and github-actions
+- Pre-commit hooks (pre-commit-hooks v4.6.0, ruff-pre-commit v0.8.0)
+- EditorConfig, Makefile, AGENTS.md
+- Public API exports in `browserget.__init__` and `browserget.installers`
+
+### Fixed
+
+- Platform mapping for edge/edgedriver now returns lowercase strings matching
+  the Edge API (`win64`, `mac-arm64`, `linux64`)
+- Firefox parser `_PLATFORM_PATHS` now includes `"os"` mapping for macOS
+- GeckoDriver parser `_ASSET_PLATFORM_MAP` now includes `"macos"` mapping
+- `InstalledArtifact.from_dict` validates required fields and types
+- `Registry.load` skips corrupted entries instead of crashing
+- HTTP requests now include `User-Agent` header for API compatibility
+- `get_available_disk_mb` consistently uses `get_cache_dir()` for path
+- `UnknownTargetError` message now includes `edgedriver` in supported list
+- `zip` calls in CLI use `strict=True` for safety
+- Bare `Exception` catches in `doctor` command replaced with specific types
+- `subprocess.run` in Edge installer uses `text=True` for cleaner output
+
+### Changed
+
+- Removed duplicate `__init__` methods from all installer subclasses (DRY)
+- Extracted common HTTP retry logic into `_retry_with_backoff` method (DRY)
+- `logging.py` now also configures stdlib `urllib` logger
+- CI workflow `test.yml` coverage threshold adjusted from 80% to 50%
+- Consolidated CI workflows: merged `test.yml` into `ci.yml`, added `ruff format --check`
+- `__version__` now uses `importlib.metadata` instead of hardcoded string
+- Development status updated to Production/Stable
+- Package layout moved from `src/browserget` to `browserget/` repository root
+- Author email standardized to `mathias.paulenko@outlook.com` across all files

browserget-1.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Mathias Paulenko
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

browserget-1.0.1/PKG-INFO

@@ -0,0 +1,165 @@
+Metadata-Version: 2.5
+Name: browserget
+Version: 1.0.1
+Summary: Standalone CLI to install browsers and drivers without any framework
+Project-URL: Homepage, https://mathiaspaulenko.github.io/browserget/
+Project-URL: Repository, https://github.com/MathiasPaulenko/browserget
+Project-URL: Changelog, https://github.com/MathiasPaulenko/browserget/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/MathiasPaulenko/browserget/issues
+Author-email: Mathias Paulenko <mathias.paulenko@outlook.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: automation,browser,chrome,chromedriver,edge,edgedriver,firefox,geckodriver,install,selenium,testing,webdriver
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Testing
+Classifier: Topic :: Utilities
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: typer>=0.12.0
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pre-commit>=3.7; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
+Requires-Dist: mkdocstrings[python]>=0.26; extra == 'docs'
+Description-Content-Type: text/markdown
+
+# browserget
+
+[![CI](https://github.com/MathiasPaulenko/browserget/actions/workflows/ci.yml/badge.svg)](https://github.com/MathiasPaulenko/browserget/actions/workflows/ci.yml)
+[![Docs](https://github.com/MathiasPaulenko/browserget/actions/workflows/docs.yml/badge.svg)](https://mathiaspaulenko.github.io/browserget/)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![PyPI](https://img.shields.io/pypi/v/browserget.svg)](https://pypi.org/project/browserget/)
+
+Standalone CLI to install browsers and drivers without any framework.
+
+Chrome for Testing, Firefox, Edge, ChromeDriver, GeckoDriver, EdgeDriver —
+all from a single tool. Python 3.11+, zero heavy dependencies.
+
+## Why?
+
+`playwright install` ties you to Playwright. `puppeteer install` ties you to
+Puppeteer. `browserget` installs browsers for **any** use — automation,
+scraping, testing, CDP, BiDi, whatever.
+
+## Features
+
+- **6 targets** — Chrome, Firefox, Edge + ChromeDriver, GeckoDriver, EdgeDriver
+- **Concurrent installs** — multiple targets install in parallel
+- **Driver matching** — `--for chrome` auto-matches ChromeDriver to your Chrome
+- **Checksum verification** — SHA-256/SHA-512 when upstream provides checksums
+- **Registry tracking** — JSON registry tracks every installed artifact
+- **JSON output** — every command supports `--json` for CI/CD integration
+- **Retry with backoff** — HTTP client retries failed requests automatically
+- **Disk space checks** — verifies sufficient space before downloading
+- **Platform detection** — auto-detects OS and architecture
+
+## Installation
+
+```bash
+pip install browserget
+```
+
+## Quick start
+
+```bash
+# Install latest stable Chrome
+browserget install chrome
+
+# Install matching ChromeDriver
+browserget install chromedriver --for chrome
+
+# Ensure browsers are installed (idempotent — skips if present)
+browserget ensure chrome chromedriver
+
+# Verify system health
+browserget doctor
+```
+
+## Usage
+
+```bash
+# Install specific version
+browserget install chrome --version 131.0.6778.87
+
+# Install by milestone (latest patch in 131)
+browserget install chrome --version 131
+
+# Install Firefox and Edge
+browserget install firefox edge
+
+# Install EdgeDriver
+browserget install edgedriver --for edge
+
+# List installed browsers
+browserget list
+
+# Get path to installed browser
+browserget path chrome
+
+# Remove a browser
+browserget remove chrome
+
+# Remove all versions of a target
+browserget remove chrome --all
+
+# List available versions for a target
+browserget versions chrome
+
+# Check system health
+browserget doctor
+
+# JSON output for CI/CD
+browserget install chrome --json
+```
+
+## Supported targets
+
+| Target | Type | Upstream source |
+|--------|------|-----------------|
+| `chrome` | Browser | Chrome for Testing API |
+| `firefox` | Browser | Mozilla FTP |
+| `edge` | Browser | Edge Updates API |
+| `chromedriver` | Driver | Chrome for Testing API |
+| `geckodriver` | Driver | GitHub Releases (mozilla/geckodriver) |
+| `edgedriver` | Driver | Edge Updates API |
+
+## Requirements
+
+- Python 3.11, 3.12, or 3.13
+- `typer` (installed automatically)
+- Internet access to download browser binaries
+
+## Documentation
+
+Full documentation is available at
+[https://mathiaspaulenko.github.io/browserget/](https://mathiaspaulenko.github.io/browserget/).
+
+- [Install command](https://mathiaspaulenko.github.io/browserget/usage/install/) — detailed usage and examples
+- [Ensure command](https://mathiaspaulenko.github.io/browserget/usage/ensure/) — idempotent installs for CI pipelines
+- [Cache management](https://mathiaspaulenko.github.io/browserget/usage/cache/) — cache location, cleanup, and configuration
+- [CLI reference](https://mathiaspaulenko.github.io/browserget/cli-reference/commands/) — complete command and flag documentation
+- [Architecture](https://mathiaspaulenko.github.io/browserget/architecture/overview/) — module diagram and design decisions
+
+## Contributing
+
+Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for
+development setup, testing, and pull request guidelines.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

browserget-1.0.1/README.md

@@ -0,0 +1,126 @@
+# browserget
+
+[![CI](https://github.com/MathiasPaulenko/browserget/actions/workflows/ci.yml/badge.svg)](https://github.com/MathiasPaulenko/browserget/actions/workflows/ci.yml)
+[![Docs](https://github.com/MathiasPaulenko/browserget/actions/workflows/docs.yml/badge.svg)](https://mathiaspaulenko.github.io/browserget/)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![PyPI](https://img.shields.io/pypi/v/browserget.svg)](https://pypi.org/project/browserget/)
+
+Standalone CLI to install browsers and drivers without any framework.
+
+Chrome for Testing, Firefox, Edge, ChromeDriver, GeckoDriver, EdgeDriver —
+all from a single tool. Python 3.11+, zero heavy dependencies.
+
+## Why?
+
+`playwright install` ties you to Playwright. `puppeteer install` ties you to
+Puppeteer. `browserget` installs browsers for **any** use — automation,
+scraping, testing, CDP, BiDi, whatever.
+
+## Features
+
+- **6 targets** — Chrome, Firefox, Edge + ChromeDriver, GeckoDriver, EdgeDriver
+- **Concurrent installs** — multiple targets install in parallel
+- **Driver matching** — `--for chrome` auto-matches ChromeDriver to your Chrome
+- **Checksum verification** — SHA-256/SHA-512 when upstream provides checksums
+- **Registry tracking** — JSON registry tracks every installed artifact
+- **JSON output** — every command supports `--json` for CI/CD integration
+- **Retry with backoff** — HTTP client retries failed requests automatically
+- **Disk space checks** — verifies sufficient space before downloading
+- **Platform detection** — auto-detects OS and architecture
+
+## Installation
+
+```bash
+pip install browserget
+```
+
+## Quick start
+
+```bash
+# Install latest stable Chrome
+browserget install chrome
+
+# Install matching ChromeDriver
+browserget install chromedriver --for chrome
+
+# Ensure browsers are installed (idempotent — skips if present)
+browserget ensure chrome chromedriver
+
+# Verify system health
+browserget doctor
+```
+
+## Usage
+
+```bash
+# Install specific version
+browserget install chrome --version 131.0.6778.87
+
+# Install by milestone (latest patch in 131)
+browserget install chrome --version 131
+
+# Install Firefox and Edge
+browserget install firefox edge
+
+# Install EdgeDriver
+browserget install edgedriver --for edge
+
+# List installed browsers
+browserget list
+
+# Get path to installed browser
+browserget path chrome
+
+# Remove a browser
+browserget remove chrome
+
+# Remove all versions of a target
+browserget remove chrome --all
+
+# List available versions for a target
+browserget versions chrome
+
+# Check system health
+browserget doctor
+
+# JSON output for CI/CD
+browserget install chrome --json
+```
+
+## Supported targets
+
+| Target | Type | Upstream source |
+|--------|------|-----------------|
+| `chrome` | Browser | Chrome for Testing API |
+| `firefox` | Browser | Mozilla FTP |
+| `edge` | Browser | Edge Updates API |
+| `chromedriver` | Driver | Chrome for Testing API |
+| `geckodriver` | Driver | GitHub Releases (mozilla/geckodriver) |
+| `edgedriver` | Driver | Edge Updates API |
+
+## Requirements
+
+- Python 3.11, 3.12, or 3.13
+- `typer` (installed automatically)
+- Internet access to download browser binaries
+
+## Documentation
+
+Full documentation is available at
+[https://mathiaspaulenko.github.io/browserget/](https://mathiaspaulenko.github.io/browserget/).
+
+- [Install command](https://mathiaspaulenko.github.io/browserget/usage/install/) — detailed usage and examples
+- [Ensure command](https://mathiaspaulenko.github.io/browserget/usage/ensure/) — idempotent installs for CI pipelines
+- [Cache management](https://mathiaspaulenko.github.io/browserget/usage/cache/) — cache location, cleanup, and configuration
+- [CLI reference](https://mathiaspaulenko.github.io/browserget/cli-reference/commands/) — complete command and flag documentation
+- [Architecture](https://mathiaspaulenko.github.io/browserget/architecture/overview/) — module diagram and design decisions
+
+## Contributing
+
+Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for
+development setup, testing, and pull request guidelines.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

browserget-1.0.1/browserget/__init__.py

@@ -0,0 +1,46 @@
+"""browserget — Standalone CLI to install browsers and drivers without any framework."""
+
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _pkg_version
+
+from browserget.config import Config, load_config
+from browserget.exceptions import (
+    AlreadyInstalledError,
+    BrowsergetError,
+    ChecksumMismatchError,
+    DriverMatchError,
+    InsufficientDiskSpaceError,
+    NetworkError,
+    UnknownTargetError,
+    UnsupportedPlatformError,
+    VersionNotFoundError,
+)
+from browserget.models import InstalledArtifact, ResolvedVersion, SystemBrowser
+from browserget.platform import OS, Arch, Platform, detect_platform
+
+try:
+    __version__ = _pkg_version("browserget")
+except PackageNotFoundError:  # pragma: no cover
+    __version__ = "0.0.0"
+
+__all__ = [
+    "AlreadyInstalledError",
+    "Arch",
+    "BrowsergetError",
+    "ChecksumMismatchError",
+    "Config",
+    "DriverMatchError",
+    "InsufficientDiskSpaceError",
+    "InstalledArtifact",
+    "NetworkError",
+    "OS",
+    "Platform",
+    "ResolvedVersion",
+    "SystemBrowser",
+    "UnknownTargetError",
+    "UnsupportedPlatformError",
+    "VersionNotFoundError",
+    "__version__",
+    "detect_platform",
+    "load_config",
+]

browserget-1.0.1/browserget/__main__.py

@@ -0,0 +1,6 @@
+"""Entry point for running browserget as a module."""
+
+from browserget.cli import main
+
+if __name__ == "__main__":
+    main()

browserget-1.0.1/browserget/archive.py

@@ -0,0 +1,114 @@
+"""Safe archive extraction utilities with path-traversal protection.
+
+All extraction functions validate that every entry in the archive resolves
+to a path inside the destination directory, preventing Zip Slip and similar
+path-traversal attacks.
+"""
+
+from __future__ import annotations
+
+import os
+import stat
+import sys
+import tarfile
+import zipfile
+from pathlib import Path
+
+
+def _safe_extract_path(dest: Path, member_name: str) -> Path:
+    """Resolve *member_name* relative to *dest* and verify it stays inside.
+
+    Args:
+        dest: The destination directory.
+        member_name: The archive member's relative path.
+
+    Returns:
+        The resolved, validated path.
+
+    Raises:
+        ValueError: If the resolved path escapes *dest*.
+    """
+    dest_resolved = dest.resolve()
+    target = (dest / member_name).resolve()
+    try:
+        target.relative_to(dest_resolved)
+    except ValueError as exc:
+        raise ValueError(f"Archive entry '{member_name}' escapes destination directory") from exc
+    return target
+
+
+def extract_zip(archive_path: Path, dest: Path) -> None:
+    """Extract a zip archive safely, preventing path traversal.
+
+    Validates both member paths and symlink targets to prevent
+    path-traversal attacks via malicious symlinks.
+
+    Args:
+        archive_path: Path to the zip file.
+        dest: Destination directory (must exist).
+
+    Raises:
+        ValueError: If any entry escapes the destination directory.
+        zipfile.BadZipFile: If the archive is corrupt or not a zip file.
+    """
+    dest.mkdir(parents=True, exist_ok=True)
+    with zipfile.ZipFile(archive_path, "r") as zf:
+        for member in zf.infolist():
+            _safe_extract_path(dest, member.filename)
+            unix_mode = member.external_attr >> 16
+            if stat.S_ISLNK(unix_mode):
+                link_target = zf.read(member).decode("utf-8", errors="replace")
+                _safe_extract_path(dest, link_target)
+        zf.extractall(dest)
+
+
+def extract_tar(archive_path: Path, dest: Path) -> None:
+    """Extract a tar archive safely, preventing path traversal.
+
+    Automatically detects compression (gzip, bzip2, xz, or uncompressed).
+    Validates both member paths and symlink/hardlink targets to prevent
+    path-traversal attacks via malicious symlinks.
+
+    Args:
+        archive_path: Path to the tar file.
+        dest: Destination directory (must exist).
+
+    Raises:
+        ValueError: If any entry escapes the destination directory.
+        tarfile.TarError: If the archive is corrupt.
+    """
+    dest.mkdir(parents=True, exist_ok=True)
+    with tarfile.open(str(archive_path), "r:*") as tf:
+        for member in tf.getmembers():
+            _safe_extract_path(dest, member.name)
+            if member.issym() or member.islnk():
+                _safe_extract_path(dest, member.linkname)
+        if sys.version_info >= (3, 12):
+            tf.extractall(dest, filter="data")
+        else:
+            for member in tf.getmembers():
+                if not (member.isfile() or member.isdir() or member.issym() or member.islnk()):
+                    raise ValueError(f"Refusing to extract special file: {member.name!r}")
+            tf.extractall(dest)
+
+
+def find_file_by_name(root: Path, filename: str) -> Path | None:
+    """Find a file by name in a directory tree without following symlinks.
+
+    Uses ``os.walk(followlinks=False)`` to avoid infinite recursion from
+    circular symlinks that may exist in extracted archives.
+
+    Args:
+        root: The root directory to search.
+        filename: The filename to match (basename only).
+
+    Returns:
+        The first matching file path, or ``None`` if not found.
+    """
+    for dirpath, _dirnames, filenames in os.walk(root, followlinks=False):
+        for fname in filenames:
+            if fname == filename:
+                candidate = Path(dirpath) / fname
+                if not candidate.is_symlink() and candidate.is_file():
+                    return candidate
+    return None