uvx-gh 0.1.0__tar.gz

uvx_gh-0.1.0/.gitignore

@@ -0,0 +1,14 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+.DS_Store
+.python-version
+.env

uvx_gh-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,62 @@
+# See https://pre-commit.com for more information
+# See https://pre-commit.com/hooks.html for more hooks
+repos:
+    - repo: https://github.com/pre-commit/pre-commit-hooks
+      rev: v6.0.0
+      hooks:
+          - id: check-yaml
+          - id: check-toml
+          - id: check-json
+          - id: check-case-conflict
+          - id: check-docstring-first
+          - id: check-added-large-files
+          - id: check-executables-have-shebangs
+          - id: debug-statements
+          - id: end-of-file-fixer
+          - id: trailing-whitespace
+            files: "\\.(py|txt|yaml|json|md|toml|lock|cfg|html|sh|js|yml)$"
+          - id: mixed-line-ending
+            files: "\\.(py|txt|yaml|json|md|toml|lock|cfg|html|sh|js|yml)$"
+          - id: fix-byte-order-marker
+          - id: name-tests-test
+          - id: requirements-txt-fixer
+
+    - repo: https://github.com/pycqa/isort
+      rev: "7.0.0"
+      hooks:
+          - id: isort
+            files: "\\.(py)$"
+            args: [--settings-path=pyproject.toml]
+
+    - repo: https://github.com/hadialqattan/pycln
+      rev: v2.6.0 # Possible releases: https://github.com/hadialqattan/pycln/releases
+      hooks:
+          - id: pycln
+            args: [--config=pyproject.toml]
+
+    - repo: https://github.com/pre-commit/mirrors-mypy
+      rev: "v1.19.1"
+      hooks:
+          - id: mypy
+            args: ["--config=pyproject.toml"]
+            additional_dependencies:
+                - pydantic
+                - pydantic_settings
+                - typer
+                - uvicorn
+                - fastapi
+                - httpx
+                - asyncache
+                - pytest
+                - types-pytz
+                - types-cachetools
+                - types-requests
+
+    - repo: https://github.com/astral-sh/ruff-pre-commit
+      rev: v0.14.14
+      hooks:
+          - id: ruff-check
+            types_or: [python, pyi]
+            args: [--fix]
+          - id: ruff-format
+            types_or: [python, pyi]

uvx_gh-0.1.0/LICENSE

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

uvx_gh-0.1.0/PKG-INFO

@@ -0,0 +1,109 @@
+Metadata-Version: 2.4
+Name: uvx-gh
+Version: 0.1.0
+Summary: Thin wrapper to uvx-run a tool from github.com/<user>/<tool>[@<ref>].
+Project-URL: Homepage, https://github.com/qsoyq/uvx-gh
+Project-URL: Repository, https://github.com/qsoyq/uvx-gh
+Project-URL: Issues, https://github.com/qsoyq/uvx-gh/issues
+Author: qsoyq
+License: MIT
+License-File: LICENSE
+Keywords: cli,github,uv,uvx,wrapper
+Classifier: Development Status :: 4 - Beta
+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 :: 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
+Classifier: Topic :: Software Development
+Classifier: Topic :: System :: Software Distribution
+Requires-Python: >=3.10
+Requires-Dist: dulwich>=0.22
+Requires-Dist: typer>=0.12
+Description-Content-Type: text/markdown
+
+# uvx-gh
+
+Thin wrapper to `uvx`-run a tool published as a GitHub repo at `github.com/<user>/<tool>[@<ref>]`.
+
+## Install
+
+```bash
+# One-off run
+uvx uvx-gh alice/foo
+
+# Or install
+pip install uvx-gh
+# pip install git+https://github.com/qsoyq/uvx-gh.git    # latest from GitHub
+```
+
+## Usage
+
+```text
+uvx-gh [uvx-options...] USER/TOOL[@REF] [tool-args...]
+uvx-gh [uvx-options...] --user USER TOOL[@REF] [tool-args...]
+```
+
+The `USER/TOOL` short path takes priority over `--user`. Either is required.
+
+### Ref suffix
+
+| Spec              | Behavior                                                                            |
+| ----------------- | ----------------------------------------------------------------------------------- |
+| `alice/foo`       | use locally cached HEAD sha; first call resolves via `git ls-remote` and persists   |
+| `alice/foo@latest`| force re-resolve HEAD via `git ls-remote` and overwrite the cached sha              |
+| `alice/foo@v1.2.3`| pin to git ref (tag / branch / sha) directly — bypasses the sha cache               |
+
+### Why the sha cache?
+
+`uvx --from git+https://...` (without a pinned commit) makes `uv` re-fetch HEAD from GitHub on every call — that's a network roundtrip per invocation. `uvx-gh` resolves HEAD itself via the smart-HTTP `ls-remote` protocol (using dulwich, no system git needed) and pins the URL to the resolved sha (`git+...@<sha>`). After the first run, subsequent calls hit the local cache and incur **zero network traffic** until you explicitly use `@latest`.
+
+Cache location:
+
+- `$UVX_GH_CACHE_HOME` if set
+- otherwise `$XDG_CACHE_HOME/uvx-gh/` (default `~/.cache/uvx-gh/`)
+
+Layout: `<cache_dir>/github.com/<user>/<tool>` containing the sha as a single line.
+
+### Pass-through
+
+Anything the wrapper does not recognize is forwarded:
+
+- Tokens before `TOOL_SPEC` go to `uvx` (e.g. `--python 3.12`, `--with extras`)
+- Tokens after `TOOL_SPEC` go to the tool itself
+- `--` ends wrapper-arg parsing; everything after `--` is treated as tool args
+
+```bash
+uvx-gh --python 3.12 alice/foo --port 8080
+# → uvx --python 3.12 --from git+https://github.com/alice/foo foo --port 8080
+
+uvx-gh -- alice/foo --user bob
+# → uvx --from git+https://github.com/alice/foo foo --user bob
+#   (--user bob is forwarded to foo, NOT consumed by uvx-gh)
+```
+
+## Requirements
+
+`uvx-gh` depends on the `uv` toolchain (which provides the `uvx` binary). It does **not** require the system `git` CLI — HEAD resolution uses [dulwich](https://github.com/jelmer/dulwich) (pure Python, bundled as a runtime dep).
+
+Install `uv`:
+
+| Platform | Command                                                          |
+| -------- | ---------------------------------------------------------------- |
+| macOS    | `brew install uv`                                                |
+| Linux    | `curl -LsSf https://astral.sh/uv/install.sh \| sh`               |
+| Windows  | `winget install --id=astral-sh.uv -e`                            |
+| Any      | `pipx install uv`                                                |
+
+`uvx-gh` runs a pre-flight check at startup and exits with a friendly message if `uvx` is not on `PATH`.
+
+## Notes
+
+- On Windows, `os.execvp` is emulated; signal/exit-code semantics differ slightly from POSIX.
+- The `UVX_VALUE_FLAGS` whitelist in `uvx_gh/commands/main.py` is hand-synced with `uv`'s value-taking flags. Use `--flag=value` form to bypass the whitelist if a new uv flag is missing.

uvx_gh-0.1.0/README.md

@@ -0,0 +1,79 @@
+# uvx-gh
+
+Thin wrapper to `uvx`-run a tool published as a GitHub repo at `github.com/<user>/<tool>[@<ref>]`.
+
+## Install
+
+```bash
+# One-off run
+uvx uvx-gh alice/foo
+
+# Or install
+pip install uvx-gh
+# pip install git+https://github.com/qsoyq/uvx-gh.git    # latest from GitHub
+```
+
+## Usage
+
+```text
+uvx-gh [uvx-options...] USER/TOOL[@REF] [tool-args...]
+uvx-gh [uvx-options...] --user USER TOOL[@REF] [tool-args...]
+```
+
+The `USER/TOOL` short path takes priority over `--user`. Either is required.
+
+### Ref suffix
+
+| Spec              | Behavior                                                                            |
+| ----------------- | ----------------------------------------------------------------------------------- |
+| `alice/foo`       | use locally cached HEAD sha; first call resolves via `git ls-remote` and persists   |
+| `alice/foo@latest`| force re-resolve HEAD via `git ls-remote` and overwrite the cached sha              |
+| `alice/foo@v1.2.3`| pin to git ref (tag / branch / sha) directly — bypasses the sha cache               |
+
+### Why the sha cache?
+
+`uvx --from git+https://...` (without a pinned commit) makes `uv` re-fetch HEAD from GitHub on every call — that's a network roundtrip per invocation. `uvx-gh` resolves HEAD itself via the smart-HTTP `ls-remote` protocol (using dulwich, no system git needed) and pins the URL to the resolved sha (`git+...@<sha>`). After the first run, subsequent calls hit the local cache and incur **zero network traffic** until you explicitly use `@latest`.
+
+Cache location:
+
+- `$UVX_GH_CACHE_HOME` if set
+- otherwise `$XDG_CACHE_HOME/uvx-gh/` (default `~/.cache/uvx-gh/`)
+
+Layout: `<cache_dir>/github.com/<user>/<tool>` containing the sha as a single line.
+
+### Pass-through
+
+Anything the wrapper does not recognize is forwarded:
+
+- Tokens before `TOOL_SPEC` go to `uvx` (e.g. `--python 3.12`, `--with extras`)
+- Tokens after `TOOL_SPEC` go to the tool itself
+- `--` ends wrapper-arg parsing; everything after `--` is treated as tool args
+
+```bash
+uvx-gh --python 3.12 alice/foo --port 8080
+# → uvx --python 3.12 --from git+https://github.com/alice/foo foo --port 8080
+
+uvx-gh -- alice/foo --user bob
+# → uvx --from git+https://github.com/alice/foo foo --user bob
+#   (--user bob is forwarded to foo, NOT consumed by uvx-gh)
+```
+
+## Requirements
+
+`uvx-gh` depends on the `uv` toolchain (which provides the `uvx` binary). It does **not** require the system `git` CLI — HEAD resolution uses [dulwich](https://github.com/jelmer/dulwich) (pure Python, bundled as a runtime dep).
+
+Install `uv`:
+
+| Platform | Command                                                          |
+| -------- | ---------------------------------------------------------------- |
+| macOS    | `brew install uv`                                                |
+| Linux    | `curl -LsSf https://astral.sh/uv/install.sh \| sh`               |
+| Windows  | `winget install --id=astral-sh.uv -e`                            |
+| Any      | `pipx install uv`                                                |
+
+`uvx-gh` runs a pre-flight check at startup and exits with a friendly message if `uvx` is not on `PATH`.
+
+## Notes
+
+- On Windows, `os.execvp` is emulated; signal/exit-code semantics differ slightly from POSIX.
+- The `UVX_VALUE_FLAGS` whitelist in `uvx_gh/commands/main.py` is hand-synced with `uv`'s value-taking flags. Use `--flag=value` form to bypass the whitelist if a new uv flag is missing.

uvx_gh-0.1.0/pyproject.toml

@@ -0,0 +1,133 @@
+[project]
+name = "uvx-gh"
+version = "0.1.0"
+description = "Thin wrapper to uvx-run a tool from github.com/<user>/<tool>[@<ref>]."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "qsoyq" }]
+keywords = ["uvx", "uv", "github", "cli", "wrapper"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "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",
+    "Topic :: Software Development",
+    "Topic :: System :: Software Distribution",
+]
+dependencies = [
+    "dulwich>=0.22",
+    "typer>=0.12",
+]
+
+[project.urls]
+Homepage = "https://github.com/qsoyq/uvx-gh"
+Repository = "https://github.com/qsoyq/uvx-gh"
+Issues = "https://github.com/qsoyq/uvx-gh/issues"
+
+[project.scripts]
+uvx-gh = "uvx_gh.commands.main:cmd"
+
+[dependency-groups]
+dev = [
+    "ipython>=8.37.0",
+    "pre-commit>=4.5.1",
+    "pytest>=8.0",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["uvx_gh"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.ruff]
+# Exclude a variety of commonly ignored directories.
+exclude = [
+    ".bzr",
+    ".direnv",
+    ".eggs",
+    ".git",
+    ".git-rewrite",
+    ".hg",
+    ".ipynb_checkpoints",
+    ".mypy_cache",
+    ".nox",
+    ".pants.d",
+    ".pyenv",
+    ".pytest_cache",
+    ".pytype",
+    ".ruff_cache",
+    ".svn",
+    ".tox",
+    ".venv",
+    ".vscode",
+    "__pypackages__",
+    "_build",
+    "buck-out",
+    "build",
+    "dist",
+    "node_modules",
+    "site-packages",
+    "venv",
+]
+# Same as Black.
+line-length = 200
+indent-width = 4
+
+[tool.ruff.lint]
+# Enable Pyflakes (`F`) and a subset of the pycodestyle (`E`)  codes by default.
+# Unlike Flake8, Ruff doesn't enable pycodestyle warnings (`W`) or
+# McCabe complexity (`C901`) by default.
+select = ["E4", "E7", "E9", "F"]
+ignore = []
+# Allow fix for all enabled rules (when `--fix`) is provided.
+fixable = ["ALL"]
+unfixable = []
+# Allow unused variables when underscore-prefixed.
+dummy-variable-rgx = "^(_+|(_+[a-zA-Z0-9_]*[a-zA-Z0-9]+?))$"
+
+[tool.ruff.format]
+# Like Black, use double quotes for strings.
+quote-style = "double"
+# Like Black, indent with spaces, rather than tabs.
+indent-style = "space"
+# Like Black, respect magic trailing commas.
+skip-magic-trailing-comma = false
+# Like Black, automatically detect the appropriate line ending.
+line-ending = "auto"
+# Enable auto-formatting of code examples in docstrings. Markdown,
+# reStructuredText code/literal blocks and doctests are all supported.
+#
+# This is currently disabled by default, but it is planned for this
+# to be opt-out in the future.
+docstring-code-format = true
+
+# Set the line length limit used when formatting code snippets in
+# docstrings.
+#
+# This only has an effect when the `docstring-code-format` setting is
+# enabled.
+# docstring-code-line-length = "dynamic"
+
+[tool.mypy]
+warn_return_any = true
+warn_unused_configs = true
+ignore_missing_imports = false
+exclude = ['^venv/', '^__init__\.py$']
+explicit_package_bases = true
+
+[tool.pytest.ini_options]
+markers = []
+
+[tool.isort]
+profile = "hug"

uvx_gh-0.1.0/tests/main_test.py

@@ -0,0 +1,5 @@
+import shutil
+
+
+def test_cmd():
+    assert shutil.which("uvx-gh") is not None