xberg-cli 1.0.0rc14__tar.gz

xberg_cli-1.0.0rc14/.gitignore

@@ -0,0 +1,323 @@
+# Build artifacts
+target/
+build/
+dist/
+.polylint/
+# Ad-hoc PDF/image debug binaries
+/check_pdf_oxide
+/check_*
+# Hand-authored WASM JS distribution files (intentionally committed)
+!crates/xberg-wasm/dist/index.js
+!crates/xberg-wasm/dist/extraction/files.js
+!crates/xberg-wasm/dist/ocr/enabler.js
+.lycheecache
+dist-musl/
+*.so
+*.dylib
+*.dll
+*.pdb
+*.node
+*.whl
+*.tar.gz
+*.gem
+*.jar
+wheels/
+**/bin/
+!**/src/bin/
+**/obj/
+
+# Rust
+*.rs.bk
+*.profraw
+rust-coverage.lcov
+rust_out
+
+# Python
+*.py[cod]
+*$py.class
+*.egg-info/
+__pycache__/
+.venv/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.hypothesis/
+.coverage
+.coverage*
+.e2e-logs/
+htmlcov/
+share/python-wheels/
+prompt_template.egg-info/
+packages/python/xberg/xberg-cli
+
+# Node.js / WASM
+node_modules/
+*.tsbuildinfo
+npm-debug.log*
+pnpm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+# NAPI-RS generated files (index.js and index.d.ts are committed for TypeScript type resolution)
+crates/xberg-node/*.tgz
+# ORT dylibs are copied to crates/xberg-node/ at build time and included in npm publish
+# despite the global *.dylib/*.so/*.dll rules below
+!crates/xberg-node/*.dylib
+!crates/xberg-node/*.so
+!crates/xberg-node/*.dll
+.wrangler/
+.pnpm-store/
+
+# Ruby
+packages/ruby/.bundle/
+packages/ruby/vendor/
+!packages/ruby/vendor/rb-sys/
+!vendor/rb-sys/build/
+!vendor/rb-sys/build/**
+*.Cache
+.yardoc/
+
+# PHP
+vendor/
+!crates/xberg-candle-ocr/src/vendor/
+php-xberg.ini
+packages/php/php-xberg.ini
+packages/php/tests.xml
+packages/php/var/
+.php-cs-fixer.cache
+
+# Swift / SwiftPM / Xcode
+.build/
+.swiftpm/
+# Legacy SwiftPM resolved-packages dir — anchored to packages/swift/ so it
+# does NOT match our top-level packages/ directory on macOS case-insensitive
+# filesystems (where the bare `Packages/` pattern previously matched and
+# silently dropped packages/dart/pubspec.yaml + 9 other scaffold files from
+# the index during regen).
+packages/swift/**/Packages/
+Package.resolved
+*.xcodeproj/
+*.xcworkspace/
+DerivedData/
+
+# Java / C# / .NET
+*.suo
+*.user
+*.cscfg
+*.cobertura.xml
+TestResults/
+
+# Generated test apps (e2e-generator --mode published)
+test_apps/
+
+# Elixir
+.nox/
+
+# Go
+packages/go/v*/install
+
+# C FFI
+crates/xberg-ffi/tests/c/test_*
+!crates/xberg-ffi/tests/c/test_*.c
+crates/xberg-ffi/tests/c/*.o
+crates/xberg-ffi/tests/c/*.dSYM/
+e2e/c/test_*
+!e2e/c/test_*.c
+e2e/c/*.o
+e2e/c/*.dSYM/
+
+# Generated pkg-config
+*.pc
+
+# Coverage
+coverage/
+coverage.info
+coverage.json
+coverage.lcov
+coverage.out
+coverage.xml
+packages/*/.coverage
+packages/*/coverage.json
+packages/*/coverage.out
+packages/*/htmlcov/
+packages/*/test-results/
+packages/*/TestResults/
+
+# IDE / Editor
+.idea/
+*.iml
+.vscode/
+.run/
+.DS_store
+
+# CI / Tools
+.cache/
+.tmp/
+*temp/
+*.temp
+*.tmp
+*.log
+**/logs/
+**/test_output.log
+.mvn/
+.tox/
+.artifacts/
+.remote-cache/
+.rumdl_cache/
+docker-logs/
+
+# Benchmarks
+benchmark-results/
+benchmark_results.json
+benchmarks/results/
+!benchmarks/baselines/
+aggregated-results/
+results/
+reports/
+tests/benchmarks/results/
+profiling-results/
+profiling-results-*/
+
+# Local perf-iteration artifacts (flamegraphs/ is committed; intermediate outputs are not)
+profile.json.gz
+profile.pb.gz
+*.heap
+bench/
+
+# Docs
+docs/_build/
+docs/build/
+docs/benchmarks/charts/
+site/
+
+# Elixir build artifacts (lock files MUST stay tracked — see CLAUDE.md
+# task-runner / dependency-awareness rules and the brotli/alloc-no-stdlib
+# regression that bit CI run 27492590406 because the NIF lock wasn't
+# committed and the resolver picked a fresh broken combo).
+packages/elixir/_build/
+packages/elixir/deps/
+e2e/elixir/_build/
+e2e/elixir/deps/
+e2e/elixir/config/
+test_documents/_build/
+test_documents/deps/
+
+# Maven plugin artifacts
+*.versionsBackup
+
+# Gradle (Kotlin e2e)
+e2e/kotlin/.gradle/
+e2e/kotlin/build/
+e2e/kotlin_android/.gradle/
+e2e/kotlin_android/build/
+
+# Ruby native build artifacts
+packages/ruby/lib/*.bundle
+packages/ruby/tmp/
+
+# Tests
+test_report.json
+tests/e2e/logs/
+tests/e2e/test_report.json
+temp-test-*
+packages/csharp/test_html_debug.cs
+
+# AI / MCP / Agent config
+.claude/
+.codex/
+.gemini/
+.xberg/
+.mcp.json
+.playwright-mcp/
+.fastembed_cache/
+*/.fastembed_cache/
+AGENTS.md
+CLAUDE.md
+GEMINI.md
+.cursorrules
+.windsurfrules
+[Tt][Oo][Dd][Oo]*
+
+# Git worktrees
+.worktrees/
+
+# Misc
+.env
+output.txt
+examples.txt
+requirements.txt
+docker-compose.yaml
+/tmp/xberg-docker-test-results.json
+tools/benchmark-harness/datasets/
+tools/benchmark-harness/.fixtures-pdf-subset/
+tools/benchmark-harness/vendored/docling/md/iso_21111_10.md
+visualizations/
+
+
+# Additional generated artifacts
+.alef/
+*.pyd
+.gems/
+vendor/bundle/
+*.h.bak
+*.test
+*.class
+bin/
+obj/
+*.nupkg
+pkg/
+
+
+# Local dev artifacts
+docs-site/public/demo-dev.html
+docs-site/dist/
+docs-site/.astro/
+demo-loaded.png
+scratch/
+
+
+.php-cs-fixer.*
+
+e2e/zig/.zig-cache/
+
+# Swift e2e build artifacts (Swift Package Manager)
+e2e/swift/.build/
+e2e/swift/.swiftpm/
+e2e/swift/Package.resolved
+e2e/swift_e2e/.build/
+e2e/swift_e2e/.swiftpm/
+e2e/swift_e2e/Package.resolved
+
+# Dart e2e build artifacts (lock file tracked for reproducibility)
+e2e/dart/.dart_tool/
+e2e/dart/build/
+
+# Dart FRB codegen cache (incremental build optimization)
+packages/dart/rust/.frb_codegen_hash
+
+# Go e2e build artifacts
+e2e/go/vendor/
+
+erl_crash.dump
+
+
+.gradle/
+
+packages/go/.lib/
+
+.build/
+
+# basemind code-map index (local tooling)
+.basemind/
+
+.bench-rc32/
+build-output-musl-node/
+
+# BEGIN ai-rulez (DO NOT EDIT - managed by ai-rulez)
+.agents/
+.ai-rulez/.generated-manifest.json
+.cursor/
+.github/agents/
+.github/commands/
+.github/copilot-instructions.md
+.github/skills/
+# END ai-rulez

xberg_cli-1.0.0rc14/PKG-INFO

@@ -0,0 +1,29 @@
+Metadata-Version: 2.4
+Name: xberg-cli
+Version: 1.0.0rc14
+Summary: CLI proxy for xberg — downloads and runs the native xberg binary from GitHub releases.
+Project-URL: Homepage, https://github.com/xberg-io/xberg
+Project-URL: Issues, https://github.com/xberg-io/xberg/issues
+Project-URL: Repository, https://github.com/xberg-io/xberg.git
+Author-email: Na'aman Hirschfeld <naaman@xberg.io>
+License: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# xberg-cli
+
+CLI proxy for [`xberg`](https://github.com/xberg-io/xberg). Installing
+this package provides a `xberg` command that downloads the matching native
+binary from GitHub releases and runs it.
+
+Pin a specific release tag with the `XBERG_CLI_VERSION` environment variable.

xberg_cli-1.0.0rc14/README.md

@@ -0,0 +1,7 @@
+# xberg-cli
+
+CLI proxy for [`xberg`](https://github.com/xberg-io/xberg). Installing
+this package provides a `xberg` command that downloads the matching native
+binary from GitHub releases and runs it.
+
+Pin a specific release tag with the `XBERG_CLI_VERSION` environment variable.

xberg_cli-1.0.0rc14/__init__.py

@@ -0,0 +1 @@
+"""Build package marker for the CLI proxy project."""

xberg_cli-1.0.0rc14/hatch_build.py

@@ -0,0 +1,151 @@
+"""Custom hatchling build hook that bundles the native xberg binary into a wheel.
+
+When building a platform-specific wheel in CI, the target triple is supplied via
+the ``XBERG_CLI_TARGET`` env var (the build host is always linux/amd64, so the
+triple cannot be inferred from ``platform.*``). The matching
+``xberg-cli-<target>.tar.gz`` / ``.zip`` is located (repo root or ``dist/``),
+the binary is extracted into ``xberg_cli/bin/<target>/``, force-included in the
+wheel, and the wheel is tagged for that platform so PyPI serves the right artifact.
+
+If no target/binary is found (e.g. the sdist build, or an unknown platform), the
+hook is a no-op and the package falls back to the runtime downloader in
+``xberg_cli/downloader.py`` (see ``cli.py``).
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import tarfile
+import zipfile
+from pathlib import Path
+
+from hatchling.builders.hooks.plugin.interface import BuildHookInterface
+
+# Rust target triple -> wheel platform tag. PyPI uses the platform tag to serve the
+# correct wheel per OS/arch/libc.
+_TAG_MAP = {
+    "x86_64-pc-windows-msvc": "win_amd64",
+    "x86_64-unknown-linux-gnu": "manylinux_2_28_x86_64",
+    "aarch64-unknown-linux-gnu": "manylinux_2_28_aarch64",
+    "x86_64-unknown-linux-musl": "musllinux_1_2_x86_64",
+    "aarch64-unknown-linux-musl": "musllinux_1_2_aarch64",
+    "aarch64-apple-darwin": "macosx_11_0_arm64",
+    "x86_64-apple-darwin": "macosx_11_0_x86_64",
+}
+
+
+def _safe_destination(root: Path, member_name: str) -> Path:
+    """Resolve an archive member path and require it to stay under root."""
+    root = root.resolve()
+    target = (root / member_name.replace("\\", "/")).resolve(strict=False)
+    if target != root and not target.is_relative_to(root):
+        raise RuntimeError(f"archive member escapes extraction directory: {member_name}")
+    return target
+
+
+def _extract_zip_bounded(archive: Path, extract_dir: Path) -> None:
+    """Extract zip entries after bounding each destination path."""
+    with zipfile.ZipFile(archive) as zf:
+        for member in zf.infolist():
+            target = _safe_destination(extract_dir, member.filename)
+            if member.is_dir():
+                target.mkdir(parents=True, exist_ok=True)
+                continue
+
+            target.parent.mkdir(parents=True, exist_ok=True)
+            with zf.open(member) as source, target.open("wb") as destination:
+                shutil.copyfileobj(source, destination)
+
+
+def _extract_tar_bounded(archive: Path, extract_dir: Path) -> None:
+    """Extract regular tar entries after bounding each destination path."""
+    with tarfile.open(archive, "r:gz") as tf:
+        for member in tf.getmembers():
+            target = _safe_destination(extract_dir, member.name)
+            if member.isdir():
+                target.mkdir(parents=True, exist_ok=True)
+                continue
+            if not member.isfile():
+                raise RuntimeError(f"unsupported archive member type: {member.name}")
+
+            target.parent.mkdir(parents=True, exist_ok=True)
+            source = tf.extractfile(member)
+            if source is None:
+                raise RuntimeError(f"could not read archive member: {member.name}")
+            with source, target.open("wb") as destination:
+                shutil.copyfileobj(source, destination)
+
+
+class CustomBuildHook(BuildHookInterface):
+    """Inject the matching native binary into a platform-tagged wheel."""
+
+    PLUGIN_NAME = "custom"
+
+    def initialize(self, version: str, build_data: dict) -> None:  # noqa: ARG002
+        """Bundle a staged native binary when building a targeted wheel."""
+        target = os.environ.get("XBERG_CLI_TARGET", "").strip()
+        if not target:
+            # sdist build or unbundled wheel: leave a pure, download-at-runtime package.
+            return
+
+        archive = self._find_archive(target)
+        if archive is None:
+            # Target requested but no binary staged — fail loudly rather than ship an
+            # empty platform wheel that shadows the working sdist on PyPI.
+            raise RuntimeError(
+                f"XBERG_CLI_TARGET={target} but no xberg-cli-{target}.(tar.gz|zip) "
+                f"found in repo root or dist/; refusing to build an empty platform wheel."
+            )
+
+        wheel_tag = _TAG_MAP.get(target)
+        if wheel_tag is None:
+            raise RuntimeError(f"no wheel platform tag mapped for target {target}")
+
+        binary = self._extract_binary(archive, target)
+
+        # force_include maps absolute source paths -> in-wheel relative paths.
+        relative = f"xberg_cli/bin/{target}/{binary.name}"
+        force_include = build_data.setdefault("force_include", {})
+        force_include[str(binary)] = relative
+
+        # Bundle runtime dylibs staged next to the binary. The native Intel-macOS
+        # build loads ONNX Runtime dynamically and ships libonnxruntime.dylib (plus
+        # its vendored deps) alongside the executable; ort resolves them relative to
+        # the binary, so they must sit in the same in-wheel directory.
+        for lib in sorted(binary.parent.glob("*.dylib")):
+            force_include[str(lib)] = f"xberg_cli/bin/{target}/{lib.name}"
+
+        # Make it a platform wheel (not pure-python, not py3-none-any).
+        build_data["pure_python"] = False
+        build_data["infer_tag"] = False
+        build_data["tag"] = f"py3-none-{wheel_tag}"
+
+    def _find_archive(self, target: str) -> Path | None:
+        root = Path(self.root)  # the project dir hatchling is building (cli-proxy/pypi)
+        repo_root = root.parent.parent
+        for base in (repo_root, repo_root / "dist", root, root / "dist"):
+            for ext in ("tar.gz", "zip"):
+                candidate = base / f"xberg-cli-{target}.{ext}"
+                if candidate.is_file():
+                    return candidate
+        return None
+
+    def _extract_binary(self, archive: Path, target: str) -> Path:
+        is_windows = target.endswith("windows-msvc")
+        binary_name = "xberg.exe" if is_windows else "xberg"
+        extract_dir = Path(self.root) / ".build-extract" / target
+        if extract_dir.exists():
+            shutil.rmtree(extract_dir, ignore_errors=True)
+        extract_dir.mkdir(parents=True, exist_ok=True)
+
+        if str(archive).lower().endswith(".zip"):
+            _extract_zip_bounded(archive, extract_dir)
+        else:
+            _extract_tar_bounded(archive, extract_dir)
+
+        for candidate in extract_dir.rglob(binary_name):
+            if candidate.is_file():
+                candidate.chmod(0o755)
+                return candidate
+        raise RuntimeError(f"binary {binary_name} not found inside {archive.name}")

xberg_cli-1.0.0rc14/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+build-backend = "hatchling.build"
+requires = ["hatchling"]
+
+[project]
+name = "xberg-cli"
+version = "1.0.0rc14"
+description = "CLI proxy for xberg — downloads and runs the native xberg binary from GitHub releases."
+readme = "README.md"
+license = { text = "MIT" }
+authors = [{ name = "Na'aman Hirschfeld", email = "naaman@xberg.io" }]
+requires-python = ">=3.10"
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+]
+urls.Homepage = "https://github.com/xberg-io/xberg"
+urls.Issues = "https://github.com/xberg-io/xberg/issues"
+urls.Repository = "https://github.com/xberg-io/xberg.git"
+scripts.xberg = "xberg_cli.cli:main"
+
+[tool.hatch]
+build.hooks.custom.path = "hatch_build.py"
+build.targets.wheel.packages = ["xberg_cli"]

xberg_cli-1.0.0rc14/xberg_cli/__init__.py

@@ -0,0 +1,3 @@
+"""CLI proxy package."""
+
+__version__ = "0.1.0"

xberg_cli-1.0.0rc14/xberg_cli/cli.py

@@ -0,0 +1,46 @@
+"""CLI entry point for the xberg proxy.
+
+A platform-specific wheel bundles the native binary under
+``xberg_cli/bin/<target>/``; the sdist (and unknown platforms) ship no binary
+and fall back to the runtime downloader. Each wheel contains exactly one ``bin/<target>``
+directory, so we locate the binary by globbing rather than recomputing the target
+triple (which cannot distinguish glibc from musl at runtime).
+"""
+
+from __future__ import annotations
+
+import os
+import platform
+import subprocess
+import sys
+from pathlib import Path
+
+from .downloader import run
+
+
+def _find_bundled_binary() -> str | None:
+    """Return the path to the bundled native binary if this wheel shipped one."""
+    bin_root = Path(__file__).parent / "bin"
+    if not bin_root.is_dir():
+        return None
+
+    binary_name = "xberg.exe" if platform.system().lower() == "windows" else "xberg"
+    for candidate in bin_root.glob(f"*/{binary_name}"):
+        if candidate.is_file() and os.access(candidate, os.X_OK):
+            return str(candidate)
+    return None
+
+
+def main() -> None:
+    """Resolve the native binary (bundled or downloaded) and exec it with forwarded argv."""
+    bundled = _find_bundled_binary()
+    if bundled:
+        completed = subprocess.run([bundled, *sys.argv[1:]], check=False)
+        sys.exit(completed.returncode)
+
+    # Fall back to the runtime download path (sdist / unknown platform).
+    sys.exit(run(sys.argv[1:]))
+
+
+if __name__ == "__main__":
+    main()

xberg_cli-1.0.0rc14/xberg_cli/downloader.py

@@ -0,0 +1,264 @@
+"""Resolve, download, verify, and run the native xberg binary.
+
+Self-healing asset discovery: query the GitHub releases API and pick the asset
+whose name contains the platform target triple, instead of hardcoding one exact
+asset name. This keeps working as release asset naming standardizes over time.
+All diagnostics go to stderr.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import platform
+import shutil
+import subprocess
+import sys
+import tarfile
+import tempfile
+import zipfile
+from pathlib import Path, PurePosixPath
+from urllib.error import URLError
+from urllib.parse import quote, urlsplit
+from urllib.request import HTTPRedirectHandler, Request, build_opener
+
+REPO = "xberg-io/xberg"
+BIN_NAME = "xberg"
+PKG_NAME = "xberg-cli"
+VERSION_ENV = "XBERG_CLI_VERSION"
+_USER_AGENT = "xberg-cli-python-proxy"
+
+
+def _target_triple() -> str:
+    system = platform.system().lower()
+    machine = platform.machine().lower()
+
+    if system == "windows":
+        if machine in {"amd64", "x86_64"}:
+            return "x86_64-pc-windows-msvc"
+        raise RuntimeError(f"unsupported Windows arch: {machine}")
+    if system == "linux":
+        if machine in {"amd64", "x86_64"}:
+            return "x86_64-unknown-linux-gnu"
+        if machine in {"aarch64", "arm64"}:
+            return "aarch64-unknown-linux-gnu"
+        raise RuntimeError(f"unsupported Linux arch: {machine}")
+    if system == "darwin":
+        if machine in {"aarch64", "arm64"}:
+            return "aarch64-apple-darwin"
+        if machine in {"amd64", "x86_64"}:
+            return "x86_64-apple-darwin"
+        raise RuntimeError(f"unsupported macOS arch: {machine}")
+    raise RuntimeError(f"unsupported platform: {system} {machine}")
+
+
+def _binary_name() -> str:
+    return f"{BIN_NAME}.exe" if platform.system().lower() == "windows" else BIN_NAME
+
+
+class _HttpsOnlyRedirectHandler(HTTPRedirectHandler):
+    """Reject any redirect whose target is not https (downgrade/SSRF guard)."""
+
+    def redirect_request(self, req, fp, code, msg, headers, newurl):  # type: ignore[no-untyped-def]
+        if urlsplit(newurl).scheme.lower() != "https":
+            raise URLError(f"refusing non-https redirect to: {newurl}")
+        return super().redirect_request(req, fp, code, msg, headers, newurl)
+
+
+_opener = build_opener(_HttpsOnlyRedirectHandler())
+
+
+def _http_get(url: str, accept: str | None = None) -> bytes:
+    if urlsplit(url).scheme.lower() != "https":
+        raise RuntimeError(f"refusing non-https URL: {url}")
+    headers = {"User-Agent": _USER_AGENT}
+    if accept:
+        headers["Accept"] = accept
+    request = Request(url, headers=headers)
+    try:
+        with _opener.open(request, timeout=60) as response:
+            if response.status != 200:
+                raise RuntimeError(f"HTTP {response.status} for {url}")
+            return response.read()
+    except URLError as exc:
+        raise RuntimeError(f"failed to fetch {url}: {exc}") from exc
+
+
+def _asset_score(name: str) -> int:
+    lowered = name.lower()
+    score = 0
+    if BIN_NAME.lower() in lowered:
+        score += 2
+    if "cli" in lowered:
+        score += 1
+    return score
+
+
+def _resolve_release() -> tuple[str, dict, dict | None]:
+    """Return (tag, archive_asset, checksums_asset_or_none) for this platform."""
+    triple = _target_triple()
+    pinned = os.getenv(VERSION_ENV)
+    if pinned:
+        api_url = f"https://api.github.com/repos/{REPO}/releases/tags/{quote(pinned, safe='')}"
+    else:
+        api_url = f"https://api.github.com/repos/{REPO}/releases/latest"
+
+    release = json.loads(_http_get(api_url, accept="application/vnd.github+json"))
+    assets = release.get("assets") or []
+    tag = release.get("tag_name") or pinned or "latest"
+
+    archives = [
+        a
+        for a in assets
+        if triple in (a.get("name") or "").lower()
+        and ((a.get("name") or "").lower().endswith(".tar.gz") or (a.get("name") or "").lower().endswith(".zip"))
+    ]
+    if not archives:
+        raise RuntimeError(f'no release asset matching target triple "{triple}" in {REPO} release {tag}')
+    archives.sort(key=lambda a: _asset_score(a.get("name") or ""), reverse=True)
+    archive = archives[0]
+
+    checksums = next((a for a in assets if "SHA256SUMS" in (a.get("name") or "").upper()), None)
+    return tag, archive, checksums
+
+
+def _expected_digest(text: str, asset_name: str) -> str | None:
+    for line in text.splitlines():
+        stripped = line.strip()
+        if not stripped:
+            continue
+        parts = stripped.split()
+        if len(parts) < 2:
+            continue
+        name = parts[-1].lstrip("*")
+        if name == asset_name:
+            return parts[0].lower()
+    return None
+
+
+def _verify_or_warn(archive_path: Path, asset_name: str, checksums: dict | None) -> None:
+    if not checksums:
+        print(
+            f"WARNING: no SHA256SUMS asset found for {asset_name}; "
+            "installing over HTTPS without checksum verification.",
+            file=sys.stderr,
+        )
+        return
+    sums_text = _http_get(checksums["browser_download_url"]).decode("utf-8")
+    expected = _expected_digest(sums_text, asset_name)
+    if not expected:
+        raise RuntimeError(
+            f"no checksum entry for {asset_name} in {checksums['name']} — refusing to install unverified binary"
+        )
+    digest = hashlib.sha256(archive_path.read_bytes()).hexdigest().lower()
+    if digest != expected:
+        raise RuntimeError(f"checksum mismatch for {asset_name} (expected {expected}, got {digest})")
+    print(f"Checksum verified for {asset_name}.", file=sys.stderr)
+
+
+def _is_within(base: Path, target: Path) -> bool:
+    """True if `target`'s resolved path stays inside `base`."""
+    base_resolved = base.resolve()
+    try:
+        target.resolve().relative_to(base_resolved)
+    except ValueError:
+        return False
+    return True
+
+
+def _reject_unsafe_member(name: str) -> None:
+    """Reject absolute paths and any `..` component (zip-slip / tar-slip)."""
+    normalized = name.replace("\\", "/")
+    pure = PurePosixPath(normalized)
+    if pure.is_absolute() or normalized.startswith("/"):
+        raise RuntimeError(f"refusing absolute path in archive: {name}")
+    # Windows drive letters / UNC prefixes are also absolute escapes.
+    if len(normalized) >= 2 and normalized[1] == ":":
+        raise RuntimeError(f"refusing absolute path in archive: {name}")
+    if any(part == ".." for part in pure.parts):
+        raise RuntimeError(f"refusing parent-directory escape in archive: {name}")
+
+
+def _safe_extract(archive_path: Path, asset_name: str, dest: Path) -> None:
+    """Extract a tar/zip, validating every member stays within `dest`.
+
+    Does not rely on extractall() defaults or the 3.12-only ``filter='data'``:
+    each member name is rejected up front if it is absolute or contains ``..``,
+    and the resolved destination path is re-checked against ``dest``.
+    """
+    dest = dest.resolve()
+    dest.mkdir(parents=True, exist_ok=True)
+
+    if asset_name.lower().endswith(".zip"):
+        with zipfile.ZipFile(archive_path) as zf:
+            for member in zf.namelist():
+                _reject_unsafe_member(member)
+                if not _is_within(dest, dest / member):
+                    raise RuntimeError(f"refusing archive entry escaping dest: {member}")
+            for member in zf.namelist():
+                zf.extract(member, dest)
+    else:
+        with tarfile.open(archive_path, "r:gz") as tf:
+            for member in tf.getmembers():
+                _reject_unsafe_member(member.name)
+                if not _is_within(dest, dest / member.name):
+                    raise RuntimeError(f"refusing archive entry escaping dest: {member.name}")
+                # Reject link members that point outside dest as well.
+                if member.islnk() or member.issym():
+                    link_target = dest / member.name
+                    if not _is_within(dest, link_target.parent / member.linkname):
+                        raise RuntimeError(f"refusing link escaping dest: {member.name}")
+            tf.extractall(dest)  # noqa: S202 (members validated above)
+
+
+def _find_binary(root: Path, name: str) -> Path | None:
+    for candidate in root.rglob(name):
+        if candidate.is_file():
+            return candidate
+    return None
+
+
+def _cache_dir(tag: str) -> Path:
+    cache = Path.home() / ".cache" / PKG_NAME / tag
+    cache.mkdir(parents=True, exist_ok=True, mode=0o700)
+    return cache
+
+
+def ensure_binary() -> str:
+    """Ensure the native binary exists locally, downloading if necessary."""
+    override = os.getenv("XBERG_BINARY")
+    if override:
+        return override
+
+    tag, archive, checksums = _resolve_release()
+    cache = _cache_dir(tag)
+    binary_path = cache / _binary_name()
+    if binary_path.exists() and os.access(binary_path, os.X_OK):
+        return str(binary_path)
+
+    print(f"Downloading {BIN_NAME} {tag} asset {archive['name']}...", file=sys.stderr)
+    with tempfile.TemporaryDirectory() as tmpdir:
+        tmp = Path(tmpdir)
+        archive_path = tmp / Path(archive["name"]).name
+        archive_path.write_bytes(_http_get(archive["browser_download_url"]))
+        _verify_or_warn(archive_path, archive["name"], checksums)
+        extract_dir = tmp / "extract"
+        extract_dir.mkdir()
+        _safe_extract(archive_path, archive["name"], extract_dir)
+        found = _find_binary(extract_dir, _binary_name())
+        if not found:
+            raise RuntimeError(f"binary {_binary_name()} not found after extracting {archive['name']}")
+        shutil.move(str(found), str(binary_path))
+
+    if platform.system().lower() != "windows":
+        binary_path.chmod(0o755)
+    print(f"{BIN_NAME} installed.", file=sys.stderr)
+    return str(binary_path)
+
+
+def run(args: list[str]) -> int:
+    """Run the native binary with the given args, returning its exit code."""
+    binary_path = ensure_binary()
+    completed = subprocess.run([binary_path, *args], check=False)
+    return completed.returncode