ohbin 0.2.2__tar.gz

ohbin-0.2.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 prostomarkeloff
+
+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.

ohbin-0.2.2/PKG-INFO

@@ -0,0 +1,161 @@
+Metadata-Version: 2.4
+Name: ohbin
+Version: 0.2.2
+Summary: Declarative GitHub-release binaries for uv projects — declare a tool in pyproject, `ohbin run <tool>` downloads, SHA256-verifies, caches, and execs it. POSIX only (uses flock).
+Author: prostomarkeloff
+Author-email: prostomarkeloff <prostomarkeloff@ohreally.me>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Dist: tomlkit>=0.13
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# ohbin
+
+[![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-yellow.svg)](https://opensource.org/licenses/MIT)
+
+ohbin runs the binaries your project needs but can't `pip install`. You know the ones:
+`ripgrep` ([or… can you?](https://pypi.org/project/ripgrep/)), [`find-dup-defs`](https://github.com/prostomarkeloff/find-dup-defs), [`oasdiff`](https://github.com/oasdiff/oasdiff), some linter
+written in Rust that only ships as a GitHub release. uv
+installs Python packages, and those aren't Python packages, so normally you're stuck either
+telling everyone to install them by hand and watching the versions drift, or writing a little
+download-and-verify wrapper package and copying it into every repo.
+
+With ohbin you just write the tool down in your `pyproject.toml`. The first time you run it,
+ohbin downloads it, checks it against a SHA256 you pinned, caches it, and runs it. One
+dev-dependency, as many tools as you want.
+
+It's a small thing on purpose, built for people who already live in uv. Your binaries get
+pinned right next to your Python deps, in the same file, and run through the same flow.
+
+What it gives you:
+
+* binaries pinned to a version, pulled from GitHub releases
+* a SHA256 per platform, checked before anything gets unpacked
+* one dev-dependency, however many tools you declare
+* a per-host cache that's safe to hit from parallel CI
+* mostly stdlib (it shells out to `gh` and `openssl` only for the private-gist part)
+
+## Installation
+
+It's a dev dependency, so with uv:
+
+```sh
+uv add --dev git+https://github.com/prostomarkeloff/ohbin.git
+```
+
+## How to?
+
+Say you want ripgrep. Point ohbin at the repo:
+
+```sh
+uv run ohbin add BurntSushi/ripgrep --version 14.1.1 --name rg --binary rg
+```
+
+This goes and looks at the release, finds the right asset for each platform, pins the SHA256s,
+and writes a little table into your `pyproject.toml`. Your comments and formatting stay where
+they are:
+
+```toml
+[tool.ohbin.tools.rg]
+repo = "BurntSushi/ripgrep"
+version = "14.1.1"
+binary = "rg"
+# add writes one [..assets.<os>-<arch>] table per platform under here, checksums and all
+```
+
+`--name` is what you'll type when it's different from the repo name (ripgrep becomes rg), and
+`--binary` is the actual executable inside the archive. If add guesses an asset wrong, don't
+fight it, the table is the source of truth, just fix the line.
+
+Then run it:
+
+```sh
+uv run ohbin run rg -- --files     # first time: downloads, checks, caches, runs
+uv run ohbin run rg -- TODO src/   # after that it just runs
+```
+
+ohbin hands the process straight over with execv, so the tool itself gets stdin, stdout,
+signals and the exit code, exactly like you'd run it yourself. In a Makefile I usually hide
+the prefix behind a variable:
+
+```make
+RG := uv run ohbin run rg --
+search:; $(RG) TODO src/
+```
+
+`ohbin which fd` prints the cached path (and downloads it first if it has to), and `ohbin list`
+shows what you've declared.
+
+### Private binaries
+
+Sometimes the binary isn't on a public release page. Maybe you built it yourself and you don't
+want it in a repo at all. ohbin can ship it through a secret gist instead, encrypted with a
+password:
+
+```sh
+uv run ohbin publish-gist ./dist/mytool --password "$PW"
+```
+
+That gzips it, encrypts it, and drops one gist file per platform plus a small index. Run it
+from each platform's own machine, passing `--gist <id>` to add to the same gist. After that
+it's just another tool:
+
+```sh
+uv run ohbin add-gist https://gist.github.com/you/ab12… --name mytool
+uv run ohbin run --password "$PW" mytool -- --help
+```
+
+Why a gist and not a private repo? Because a gist isn't tied to a repo, and that's the whole
+point. You don't commit the binary anywhere, you don't hand out repo access and tokens to
+everyone who needs it, you just give them a link and a password. The link is unlisted and the
+bytes are AES-256-CBC, so a leaked link on its own is nothing without the password. The
+password goes to openssl over a file descriptor, never on the command line. To take access
+away, delete the gist or change the password.
+
+### From Python
+
+If you want the path instead of running the thing:
+
+```python
+from ohbin import ensure
+
+path = ensure("rg")   # a Path, downloaded and checked the first time
+```
+
+It finds your `pyproject.toml` by walking up from wherever you are. Set `OHBIN_PYPROJECT` if
+you need to point it at a specific file, like in CI.
+
+## How it works
+
+Nothing clever. On `ohbin run rg`, it reads the rg table, works out your os and arch, and looks
+for `~/.cache/ohbin/rg/14.1.1/rg`. If it's there, it runs it. If not, it downloads under a lock
+(so two parallel runs don't race), checks the SHA256 before unpacking anything, extracts, and
+runs. The version is in the cache path, so bumping it is just a fresh download that doesn't step
+on the old one. Downloads retry with backoff, and a real 404 doesn't get mistaken for a flaky
+network.
+
+## Limitations
+
+POSIX only for now, the locking uses `fcntl` so it won't even import on Windows. add
+auto-resolves four platforms (linux and macOS, x86_64 and arm64); anything else (windows, musl,
+riscv) you add to the table by hand and the engine runs it fine. Asset matching is just looking
+at the os/arch words in the filename and preferring `.tar.gz`, so a weird naming scheme might
+cost you a one-line fix.
+
+## Development
+
+```sh
+git clone https://github.com/prostomarkeloff/ohbin
+cd ohbin && uv sync
+
+make lint-heavy   # ruff format + check + pyright
+make test-full    # the network-free test suite
+```
+
+## License
+
+MIT, see [LICENSE](LICENSE).
+
+Made with 📦 by [prostomarkeloff](https://github.com/prostomarkeloff) and contributors.

ohbin-0.2.2/README.md

@@ -0,0 +1,149 @@
+# ohbin
+
+[![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-yellow.svg)](https://opensource.org/licenses/MIT)
+
+ohbin runs the binaries your project needs but can't `pip install`. You know the ones:
+`ripgrep` ([or… can you?](https://pypi.org/project/ripgrep/)), [`find-dup-defs`](https://github.com/prostomarkeloff/find-dup-defs), [`oasdiff`](https://github.com/oasdiff/oasdiff), some linter
+written in Rust that only ships as a GitHub release. uv
+installs Python packages, and those aren't Python packages, so normally you're stuck either
+telling everyone to install them by hand and watching the versions drift, or writing a little
+download-and-verify wrapper package and copying it into every repo.
+
+With ohbin you just write the tool down in your `pyproject.toml`. The first time you run it,
+ohbin downloads it, checks it against a SHA256 you pinned, caches it, and runs it. One
+dev-dependency, as many tools as you want.
+
+It's a small thing on purpose, built for people who already live in uv. Your binaries get
+pinned right next to your Python deps, in the same file, and run through the same flow.
+
+What it gives you:
+
+* binaries pinned to a version, pulled from GitHub releases
+* a SHA256 per platform, checked before anything gets unpacked
+* one dev-dependency, however many tools you declare
+* a per-host cache that's safe to hit from parallel CI
+* mostly stdlib (it shells out to `gh` and `openssl` only for the private-gist part)
+
+## Installation
+
+It's a dev dependency, so with uv:
+
+```sh
+uv add --dev git+https://github.com/prostomarkeloff/ohbin.git
+```
+
+## How to?
+
+Say you want ripgrep. Point ohbin at the repo:
+
+```sh
+uv run ohbin add BurntSushi/ripgrep --version 14.1.1 --name rg --binary rg
+```
+
+This goes and looks at the release, finds the right asset for each platform, pins the SHA256s,
+and writes a little table into your `pyproject.toml`. Your comments and formatting stay where
+they are:
+
+```toml
+[tool.ohbin.tools.rg]
+repo = "BurntSushi/ripgrep"
+version = "14.1.1"
+binary = "rg"
+# add writes one [..assets.<os>-<arch>] table per platform under here, checksums and all
+```
+
+`--name` is what you'll type when it's different from the repo name (ripgrep becomes rg), and
+`--binary` is the actual executable inside the archive. If add guesses an asset wrong, don't
+fight it, the table is the source of truth, just fix the line.
+
+Then run it:
+
+```sh
+uv run ohbin run rg -- --files     # first time: downloads, checks, caches, runs
+uv run ohbin run rg -- TODO src/   # after that it just runs
+```
+
+ohbin hands the process straight over with execv, so the tool itself gets stdin, stdout,
+signals and the exit code, exactly like you'd run it yourself. In a Makefile I usually hide
+the prefix behind a variable:
+
+```make
+RG := uv run ohbin run rg --
+search:; $(RG) TODO src/
+```
+
+`ohbin which fd` prints the cached path (and downloads it first if it has to), and `ohbin list`
+shows what you've declared.
+
+### Private binaries
+
+Sometimes the binary isn't on a public release page. Maybe you built it yourself and you don't
+want it in a repo at all. ohbin can ship it through a secret gist instead, encrypted with a
+password:
+
+```sh
+uv run ohbin publish-gist ./dist/mytool --password "$PW"
+```
+
+That gzips it, encrypts it, and drops one gist file per platform plus a small index. Run it
+from each platform's own machine, passing `--gist <id>` to add to the same gist. After that
+it's just another tool:
+
+```sh
+uv run ohbin add-gist https://gist.github.com/you/ab12… --name mytool
+uv run ohbin run --password "$PW" mytool -- --help
+```
+
+Why a gist and not a private repo? Because a gist isn't tied to a repo, and that's the whole
+point. You don't commit the binary anywhere, you don't hand out repo access and tokens to
+everyone who needs it, you just give them a link and a password. The link is unlisted and the
+bytes are AES-256-CBC, so a leaked link on its own is nothing without the password. The
+password goes to openssl over a file descriptor, never on the command line. To take access
+away, delete the gist or change the password.
+
+### From Python
+
+If you want the path instead of running the thing:
+
+```python
+from ohbin import ensure
+
+path = ensure("rg")   # a Path, downloaded and checked the first time
+```
+
+It finds your `pyproject.toml` by walking up from wherever you are. Set `OHBIN_PYPROJECT` if
+you need to point it at a specific file, like in CI.
+
+## How it works
+
+Nothing clever. On `ohbin run rg`, it reads the rg table, works out your os and arch, and looks
+for `~/.cache/ohbin/rg/14.1.1/rg`. If it's there, it runs it. If not, it downloads under a lock
+(so two parallel runs don't race), checks the SHA256 before unpacking anything, extracts, and
+runs. The version is in the cache path, so bumping it is just a fresh download that doesn't step
+on the old one. Downloads retry with backoff, and a real 404 doesn't get mistaken for a flaky
+network.
+
+## Limitations
+
+POSIX only for now, the locking uses `fcntl` so it won't even import on Windows. add
+auto-resolves four platforms (linux and macOS, x86_64 and arm64); anything else (windows, musl,
+riscv) you add to the table by hand and the engine runs it fine. Asset matching is just looking
+at the os/arch words in the filename and preferring `.tar.gz`, so a weird naming scheme might
+cost you a one-line fix.
+
+## Development
+
+```sh
+git clone https://github.com/prostomarkeloff/ohbin
+cd ohbin && uv sync
+
+make lint-heavy   # ruff format + check + pyright
+make test-full    # the network-free test suite
+```
+
+## License
+
+MIT, see [LICENSE](LICENSE).
+
+Made with 📦 by [prostomarkeloff](https://github.com/prostomarkeloff) and contributors.

ohbin-0.2.2/pyproject.toml

@@ -0,0 +1,51 @@
+[project]
+name = "ohbin"
+version = "0.2.2"
+description = "Declarative GitHub-release binaries for uv projects — declare a tool in pyproject, `ohbin run <tool>` downloads, SHA256-verifies, caches, and execs it. POSIX only (uses flock)."
+readme = "README.md"
+authors = [
+    { name = "prostomarkeloff", email = "prostomarkeloff@ohreally.me" }
+]
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+# Hot path (`run` / `ensure`) is pure stdlib. tomlkit is only imported by `add`,
+# which edits pyproject.toml and must preserve its comments/formatting.
+dependencies = [
+    "tomlkit>=0.13",
+]
+
+[project.scripts]
+ohbin = "ohbin.cli:main"
+
+[dependency-groups]
+dev = [
+    "pyright>=1.1.409",
+    "pytest>=8.0",
+    "ruff>=0.15.14",
+]
+
+[build-system]
+requires = ["uv_build>=0.8.1,<0.9.0"]
+build-backend = "uv_build"
+
+[tool.ruff]
+target-version = "py311"
+line-length = 120
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+# Conservative ruleset: errors/warnings, pyflakes, isort, bugbear, pyupgrade,
+# naming, comprehensions, simplify, ruff-specific.
+select = ["E", "F", "W", "I", "B", "UP", "N", "C4", "SIM", "RUF"]
+
+[tool.ruff.lint.per-file-ignores]
+# Tests intentionally reach into `_*`-prefixed internals.
+"tests/*" = ["SLF001"]
+
+[tool.pyright]
+include = ["src", "tests"]
+pythonVersion = "3.11"
+typeCheckingMode = "basic"
+reportMissingImports = true
+reportUnusedImport = true

ohbin-0.2.2/src/ohbin/__init__.py

@@ -0,0 +1,95 @@
+"""ohbin — declarative GitHub-release binaries for uv projects.
+
+Declare tools in your project's pyproject:
+
+    [tool.ohbin.tools.rg]
+    repo = "BurntSushi/ripgrep"
+    version = "14.1.1"
+    binary = "rg"
+
+    [tool.ohbin.tools.rg.assets.darwin-arm64]
+    url = "https://github.com/BurntSushi/ripgrep/releases/download/14.1.1/ripgrep-14.1.1-aarch64-apple-darwin.tar.gz"
+    sha256 = "..."
+
+then `uv run ohbin run rg -- <args>`, or in-process `ohbin.ensure("rg")`.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+from ohbin._engine import (
+    BinaryNotFoundError,
+    ChecksumMismatchError,
+    MissingPasswordError,
+    cache_root,
+    ensure_from,
+)
+from ohbin._errors import OhbinError
+from ohbin._manifest import ManifestError, find_pyproject, load_tool, load_tools
+from ohbin._platform import Platform, UnsupportedPlatformError, current_platform
+from ohbin._types import AssetEntry, ToolConfig
+
+__all__ = [
+    "AssetEntry",
+    "BinaryNotFoundError",
+    "ChecksumMismatchError",
+    "ManifestError",
+    "MissingPasswordError",
+    "OhbinError",
+    "Platform",
+    "ToolConfig",
+    "UnsupportedPlatformError",
+    "cache_root",
+    "current_platform",
+    "ensure",
+    "ensure_from",
+    "find_pyproject",
+    "load_tool",
+    "load_tools",
+]
+
+
+def _resolve_password(tool: str, cfg: ToolConfig, explicit: str | None) -> str | None:
+    """`--password` wins; otherwise fall back to the manifest, warning unless ack'd."""
+    if explicit is not None:
+        return explicit
+    pw = cfg.get("password")
+    if pw is not None and not cfg.get("password_committed_ok"):
+        print(
+            f"ohbin: warning: reading the password for {tool!r} from pyproject — keep it out "
+            "of public repos; set 'password_committed_ok = true' to silence this.",
+            file=sys.stderr,
+        )
+    return pw
+
+
+def ensure(tool: str, *, pyproject: Path | None = None, password: str | None = None) -> Path:
+    """Return the cached binary path for a declared tool, downloading on first use.
+
+    Reads `[tool.ohbin.tools.<tool>]` from the project's pyproject (discovered
+    from CWD, or `OHBIN_PYPROJECT`). This is the in-process entry point — call it
+    from build tooling that needs the binary's path rather than exec-ing it.
+
+    For encrypted tools, `password` (from `--password`) takes precedence over the
+    manifest's `password` field.
+    """
+    cfg = load_tool(tool, pyproject=pyproject)
+    plat = current_platform()
+    entry = cfg["assets"].get(plat.key)
+    if entry is None:
+        declared = ", ".join(sorted(cfg["assets"])) or "none"
+        msg = f"tool {tool!r} has no asset for {plat.key} (declared: {declared})"
+        raise UnsupportedPlatformError(msg)
+    encrypted = bool(cfg.get("encrypted"))
+    return ensure_from(
+        tool=tool,
+        version=cfg["version"],
+        binary=cfg["binary"],
+        url=entry["url"],
+        sha256=entry["sha256"],
+        encrypted=encrypted,
+        password=_resolve_password(tool, cfg, password) if encrypted else None,
+        binary_sha256=entry.get("binary_sha256"),
+    )

ohbin-0.2.2/src/ohbin/__main__.py

@@ -0,0 +1,10 @@
+"""Allow `python -m ohbin`."""
+
+from __future__ import annotations
+
+import sys
+
+from ohbin.cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())