uv-launch 0.1.1__tar.gz

uv_launch-0.1.1/PKG-INFO

@@ -0,0 +1,57 @@
+Metadata-Version: 2.3
+Name: uv-launch
+Version: 0.1.1
+Summary: Immediate Python command startup with atomic background updates through uv
+Requires-Python: >=3.11
+Project-URL: Repository, https://github.com/nimashoghi/uv-launch
+Description-Content-Type: text/markdown
+
+# uv-launch
+
+Install Python commands that start immediately and update in the background. The foreground shell shim executes an already installed environment. It does not invoke uv or wait for network access.
+
+Requires macOS or Linux, Python 3.11+, and [uv](https://docs.astral.sh/uv/). Install this tool into a stable environment with `uv tool install uv-launch` from [PyPI](https://pypi.org/project/uv-launch/). `uvx uv-launch --help` also runs the CLI without a tool installation; use the stable tool installation for long-lived managed commands because their background updater uses its Python environment. Then install commands:
+
+```sh
+uv-launch install ruff ruff
+uv-launch install my-command 'package-name @ git+https://github.com/owner/project.git@main' \
+  --entrypoint actual-console-script --with another-package --python 3.13
+my-command --help
+uv-launch update my-command
+uv-launch status my-command
+```
+
+`--bin-dir` defaults to `~/.local/bin`. Use a separate directory for evaluation. The installer refuses to overwrite commands it does not own. `UV_LAUNCH_HOME` selects the installation-state directory; its default is `~/.local/share/uv-launch`.
+
+Each invocation captures the current immutable generation and starts a detached update check. Concurrent checks for the same tool coalesce under a process lock. A check resolves all requested packages together, pinning Git dependencies to concrete revisions. If the resolved installation is unchanged, it keeps the existing environment. Otherwise it creates a new environment at its final path, checks dependencies and loads the Python entrypoint (or verifies ownership of a wheel-provided executable), then atomically switches the generation used by future launches. Virtual environments are never moved after creation, because their scripts contain absolute paths.
+
+The launched command retains its arguments, working directory, environment and exit status. Updates never mutate its environment. An offline or failed update leaves the installed version usable. `status` reports the current generation and the last completed update result; background diagnostics are in `<UV_LAUNCH_HOME>/<command>/update.log`. Checks use the existing uv/Git authentication configuration and do not change it.
+
+An initial installation requires dependency access. Automatic updates have a 600-second timeout per subprocess by default; configure it with `install --timeout`. Validation checks installation and entrypoint integrity, not application-specific behavior. Keep old generations while processes may still use them; this release deliberately does not automatically delete them. Reinstalling this launcher itself is explicit, using `uv tool upgrade uv-launch`.
+
+## Codex-router example
+
+All five packages are resolved in one operation, so a moving Git ref produces one consistent suite revision:
+
+```sh
+uv-launch install codexr \
+  'codex-router @ git+https://github.com/nimashoghi/codex-router.git@main#subdirectory=packages/codex-router' \
+  --with 'codex-router-sdk @ git+https://github.com/nimashoghi/codex-router.git@main#subdirectory=packages/codex-router-sdk' \
+  --with 'codex-monitor @ git+https://github.com/nimashoghi/codex-router.git@main#subdirectory=packages/codex-monitor' \
+  --with 'codex-recovery @ git+https://github.com/nimashoghi/codex-router.git@main#subdirectory=packages/codex-recovery' \
+  --with 'codex-accounts @ git+https://github.com/nimashoghi/codex-router.git@main#subdirectory=packages/codex-accounts' \
+  --bin-dir ~/.local/share/codexr-evaluation/bin
+```
+
+Use that isolated command before choosing to replace an existing launcher. Updating the local codexr suite and preparing that exact suite on an SSH host remain separate responsibilities; uv-launch contains no Codex or SSH runtime logic.
+
+## Development
+
+```sh
+uv sync
+uv run pytest -q
+uv run ruff check .
+uv run ruff format --check .
+```
+
+Integration tests create local Git packages and exercise installation, immutable revisions, background publication, failed updates, concurrent checks, offline launches, and preservation of unrelated commands.

uv_launch-0.1.1/README.md

@@ -0,0 +1,49 @@
+# uv-launch
+
+Install Python commands that start immediately and update in the background. The foreground shell shim executes an already installed environment. It does not invoke uv or wait for network access.
+
+Requires macOS or Linux, Python 3.11+, and [uv](https://docs.astral.sh/uv/). Install this tool into a stable environment with `uv tool install uv-launch` from [PyPI](https://pypi.org/project/uv-launch/). `uvx uv-launch --help` also runs the CLI without a tool installation; use the stable tool installation for long-lived managed commands because their background updater uses its Python environment. Then install commands:
+
+```sh
+uv-launch install ruff ruff
+uv-launch install my-command 'package-name @ git+https://github.com/owner/project.git@main' \
+  --entrypoint actual-console-script --with another-package --python 3.13
+my-command --help
+uv-launch update my-command
+uv-launch status my-command
+```
+
+`--bin-dir` defaults to `~/.local/bin`. Use a separate directory for evaluation. The installer refuses to overwrite commands it does not own. `UV_LAUNCH_HOME` selects the installation-state directory; its default is `~/.local/share/uv-launch`.
+
+Each invocation captures the current immutable generation and starts a detached update check. Concurrent checks for the same tool coalesce under a process lock. A check resolves all requested packages together, pinning Git dependencies to concrete revisions. If the resolved installation is unchanged, it keeps the existing environment. Otherwise it creates a new environment at its final path, checks dependencies and loads the Python entrypoint (or verifies ownership of a wheel-provided executable), then atomically switches the generation used by future launches. Virtual environments are never moved after creation, because their scripts contain absolute paths.
+
+The launched command retains its arguments, working directory, environment and exit status. Updates never mutate its environment. An offline or failed update leaves the installed version usable. `status` reports the current generation and the last completed update result; background diagnostics are in `<UV_LAUNCH_HOME>/<command>/update.log`. Checks use the existing uv/Git authentication configuration and do not change it.
+
+An initial installation requires dependency access. Automatic updates have a 600-second timeout per subprocess by default; configure it with `install --timeout`. Validation checks installation and entrypoint integrity, not application-specific behavior. Keep old generations while processes may still use them; this release deliberately does not automatically delete them. Reinstalling this launcher itself is explicit, using `uv tool upgrade uv-launch`.
+
+## Codex-router example
+
+All five packages are resolved in one operation, so a moving Git ref produces one consistent suite revision:
+
+```sh
+uv-launch install codexr \
+  'codex-router @ git+https://github.com/nimashoghi/codex-router.git@main#subdirectory=packages/codex-router' \
+  --with 'codex-router-sdk @ git+https://github.com/nimashoghi/codex-router.git@main#subdirectory=packages/codex-router-sdk' \
+  --with 'codex-monitor @ git+https://github.com/nimashoghi/codex-router.git@main#subdirectory=packages/codex-monitor' \
+  --with 'codex-recovery @ git+https://github.com/nimashoghi/codex-router.git@main#subdirectory=packages/codex-recovery' \
+  --with 'codex-accounts @ git+https://github.com/nimashoghi/codex-router.git@main#subdirectory=packages/codex-accounts' \
+  --bin-dir ~/.local/share/codexr-evaluation/bin
+```
+
+Use that isolated command before choosing to replace an existing launcher. Updating the local codexr suite and preparing that exact suite on an SSH host remain separate responsibilities; uv-launch contains no Codex or SSH runtime logic.
+
+## Development
+
+```sh
+uv sync
+uv run pytest -q
+uv run ruff check .
+uv run ruff format --check .
+```
+
+Integration tests create local Git packages and exercise installation, immutable revisions, background publication, failed updates, concurrent checks, offline launches, and preservation of unrelated commands.

uv_launch-0.1.1/pyproject.toml

@@ -0,0 +1,38 @@
+[project]
+name = "uv-launch"
+version = "0.1.1"
+description = "Immediate Python command startup with atomic background updates through uv"
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = []
+
+[project.urls]
+Repository = "https://github.com/nimashoghi/uv-launch"
+
+[project.scripts]
+uv-launch = "uv_launch:main"
+
+[build-system]
+requires = ["uv_build>=0.11,<0.12"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=8,<10",
+    "ruff>=0.12",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "F",
+    "I",
+    "UP",
+    "B",
+    "SIM",
+    "RUF",
+]

uv_launch-0.1.1/pyproject.toml.orig

@@ -0,0 +1,27 @@
+[project]
+name = "uv-launch"
+version = "0.1.1"
+description = "Immediate Python command startup with atomic background updates through uv"
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = []
+
+[project.urls]
+Repository = "https://github.com/nimashoghi/uv-launch"
+
+[project.scripts]
+uv-launch = "uv_launch:main"
+
+[build-system]
+requires = ["uv_build>=0.11,<0.12"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = ["pytest>=8,<10", "ruff>=0.12"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM", "RUF"]

uv_launch-0.1.1/src/uv_launch/__init__.py

@@ -0,0 +1,309 @@
+"""Launch installed Python commands immediately and update future launches with uv."""
+
+from __future__ import annotations
+
+import argparse
+import fcntl
+import hashlib
+import json
+import logging
+import os
+import re
+import shlex
+import shutil
+import subprocess
+import sys
+import tempfile
+import time
+import uuid
+from contextlib import contextmanager
+from pathlib import Path
+
+LOGGER = logging.getLogger(__name__)
+
+
+def state_root() -> Path:
+    """Return durable installation state, independently of any current project."""
+    return (
+        Path(os.environ.get("UV_LAUNCH_HOME", "~/.local/share/uv-launch")).expanduser().absolute()
+    )
+
+
+def tool_directory(name: str) -> Path:
+    if not re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9._-]*", name):
+        raise ValueError("command names must contain only letters, digits, '.', '_' and '-'")
+    return state_root() / name
+
+
+def atomic_write(path: Path, content: str, mode: int = 0o600) -> None:
+    descriptor, temporary = tempfile.mkstemp(prefix=f".{path.name}-", dir=path.parent)
+    try:
+        with os.fdopen(descriptor, "w") as stream:
+            stream.write(content)
+        os.chmod(temporary, mode)
+        os.replace(temporary, path)
+    finally:
+        Path(temporary).unlink(missing_ok=True)
+
+
+@contextmanager
+def installation_lock(root: Path, *, background: bool = False):
+    root.mkdir(parents=True, exist_ok=True, mode=0o700)
+    with (root / "update.lock").open("a+") as lock:
+        try:
+            fcntl.flock(lock, fcntl.LOCK_EX | (fcntl.LOCK_NB if background else 0))
+        except BlockingIOError:
+            yield False
+        else:
+            try:
+                yield True
+            finally:
+                fcntl.flock(lock, fcntl.LOCK_UN)
+
+
+def run_uv(config: dict, arguments: list[str], *, cwd: Path) -> None:
+    subprocess.run(
+        [config["uv"], "--no-config", "--no-progress", *arguments],
+        cwd=cwd,
+        stdin=subprocess.DEVNULL,
+        stdout=subprocess.DEVNULL,
+        check=True,
+        timeout=config["timeout"],
+    )
+
+
+def refresh(root: Path, config: dict) -> dict:
+    """Prepare an immutable candidate; publish only after dependency and entrypoint checks."""
+    generations = root / "generations"
+    generations.mkdir(exist_ok=True)
+    candidate = generations / uuid.uuid4().hex
+    candidate.mkdir(mode=0o700)
+    published = False
+    try:
+        requirements = candidate / "requirements.in"
+        requirements.write_text("\n".join(config["requirements"]) + "\n")
+        lock = candidate / "requirements.txt"
+        # One resolution pins shared Git sources once for all requested packages.
+        # The resulting immutable revisions are reused when installing the candidate.
+        run_uv(
+            config,
+            [
+                "pip",
+                "compile",
+                str(requirements),
+                "--output-file",
+                str(lock),
+                "--no-header",
+                "--no-annotate",
+                "--refresh",
+                "--python",
+                config["python"],
+            ],
+            cwd=root,
+        )
+        identity = hashlib.sha256(
+            (json.dumps(config, sort_keys=True) + "\n" + lock.read_text()).encode()
+        ).hexdigest()
+        current = root / "current"
+        if current.exists():
+            previous = json.loads((current / "installation.json").read_text())
+            if previous["identity"] == identity:
+                return {"status": "unchanged", **previous}
+        # Never move a virtualenv: entrypoint shebangs contain its absolute path.
+        environment = candidate / "venv"
+        run_uv(config, ["venv", "--python", config["python"], str(environment)], cwd=root)
+        run_uv(
+            config,
+            [
+                "pip",
+                "sync",
+                "--python",
+                str(environment / "bin/python"),
+                "--link-mode",
+                "copy",
+                "--strict",
+                str(lock),
+            ],
+            cwd=root,
+        )
+        executable = environment / "bin" / config["entrypoint"]
+        if not executable.is_file() or not os.access(executable, os.X_OK):
+            raise ValueError(f"installed environment does not provide {config['entrypoint']!r}")
+        # Import Python entrypoints to catch missing callables before publication.
+        # Wheel-provided executables need an owning distribution instead.
+        subprocess.run(
+            [
+                str(environment / "bin/python"),
+                "-I",
+                "-c",
+                "import importlib.metadata as m, pathlib, sys\n"
+                "entries=list(m.entry_points(group='console_scripts', name=sys.argv[1]))\n"
+                "assert len(entries)<=1, 'ambiguous console entrypoint'\n"
+                "if entries:\n"
+                "    assert callable(entries[0].load()), 'entrypoint must be callable'\n"
+                "else:\n"
+                "    executable=pathlib.Path(sys.argv[2]).resolve()\n"
+                "    owners=[d for d in m.distributions() if any(\n"
+                "        pathlib.Path(d.locate_file(f)).resolve()==executable\n"
+                "        for f in d.files or ())]\n"
+                "    assert len(owners)==1, 'expected one distribution owning the executable'\n",
+                config["entrypoint"],
+                str(executable),
+            ],
+            check=True,
+            stdin=subprocess.DEVNULL,
+            stdout=subprocess.DEVNULL,
+            timeout=config["timeout"],
+        )
+        metadata = {"identity": identity, "generation": str(candidate), "created_at": time.time()}
+        atomic_write(candidate / "installation.json", json.dumps(metadata, sort_keys=True))
+        atomic_write(candidate / "config.json", json.dumps(config, indent=2) + "\n")
+        (candidate / "command").symlink_to(executable.relative_to(candidate))
+        link = root / f".current-{uuid.uuid4().hex}"
+        try:
+            link.symlink_to(candidate.relative_to(root), target_is_directory=True)
+            os.replace(link, current)
+        finally:
+            link.unlink(missing_ok=True)
+        published = True
+        return {"status": "updated", **metadata}
+    finally:
+        if not published:
+            shutil.rmtree(candidate)
+
+
+def write_launcher(root: Path, config: dict) -> Path:
+    """Install a shell shim with no foreground Python or package resolution overhead."""
+    destination = Path(config["bin_dir"]) / config["name"]
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    python = shlex.quote(sys.executable)
+    home = shlex.quote(str(root.parent))
+    name = shlex.quote(config["name"])
+    directory = shlex.quote(str(root))
+    content = (
+        "#!/bin/sh\n"
+        f"# Managed by uv-launch: {config['name']}\n"
+        # Read one immutable generation before the updater can switch current.
+        f"generation=$(readlink {directory}/current) || exit 1\n"
+        f"UV_LAUNCH_HOME={home} nohup {python} -I -m uv_launch update {name} "
+        "--background </dev/null >/dev/null 2>&1 &\n"
+        f'exec {directory}/"$generation"/command "$@"\n'
+    )
+    if destination.exists() and not destination.read_text().startswith(
+        f"#!/bin/sh\n# Managed by uv-launch: {config['name']}\n"
+    ):
+        raise ValueError(f"refusing to replace an unmanaged command: {destination}")
+    atomic_write(destination, content, 0o755)
+    return destination
+
+
+def install(args: argparse.Namespace) -> dict:
+    """Install a named command; existing unrelated launchers are never replaced."""
+    root = tool_directory(args.name)
+    tool_directory(args.entrypoint or args.name)
+    uv = shutil.which("uv")
+    if uv is None:
+        raise ValueError("uv must be installed and available on PATH")
+    config = {
+        "name": args.name,
+        "entrypoint": args.entrypoint or args.name,
+        "requirements": [args.requirement, *args.extra],
+        "python": args.python,
+        "uv": uv,
+        "timeout": args.timeout,
+        "bin_dir": str(Path(args.bin_dir).expanduser().absolute()),
+    }
+    for requirement in config["requirements"]:
+        if not requirement or "\n" in requirement or "\r" in requirement:
+            raise ValueError("each requirement must be a single nonempty line")
+    destination = Path(config["bin_dir"]) / config["name"]
+    if destination.exists() and not destination.read_text().startswith(
+        f"#!/bin/sh\n# Managed by uv-launch: {config['name']}\n"
+    ):
+        raise ValueError(f"refusing to replace an unmanaged command: {destination}")
+    with installation_lock(root):
+        result = refresh(root, config)
+        destination = write_launcher(root, config)
+    return {**result, "command": str(destination)}
+
+
+def update(name: str, *, background: bool = False) -> dict:
+    """Update a tool without changing any running generation; coalesce concurrent checks."""
+    root = tool_directory(name)
+    with installation_lock(root, background=background) as acquired:
+        if not acquired:
+            return {"status": "already-checking"}
+        config = json.loads((root / "current/config.json").read_text())
+        try:
+            if background:
+                # Only the lock owner opens this log, so coalesced checks cannot
+                # truncate another update's diagnostics.
+                with (root / "update.log").open("w") as log:
+                    os.dup2(log.fileno(), sys.stderr.fileno())
+                    result = refresh(root, config)
+            else:
+                result = refresh(root, config)
+        except (OSError, ValueError, subprocess.SubprocessError) as error:
+            atomic_write(
+                root / "last-update.json",
+                json.dumps(
+                    {
+                        "status": "failed",
+                        "error": str(error),
+                        "checked_at": time.time(),
+                    }
+                ),
+            )
+            raise
+        else:
+            atomic_write(
+                root / "last-update.json", json.dumps({**result, "checked_at": time.time()})
+            )
+            return result
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Command-line interface for installing, updating and inspecting named tools."""
+    parser = argparse.ArgumentParser(description=__doc__)
+    commands = parser.add_subparsers(dest="command", required=True)
+    installing = commands.add_parser("install", help="install an immediately runnable command")
+    installing.add_argument("name", help="name of the generated command")
+    installing.add_argument("requirement", help="Python package requirement or Git URL")
+    installing.add_argument("--with", dest="extra", action="append", default=[])
+    installing.add_argument(
+        "--entrypoint", help="installed console script, defaults to command name"
+    )
+    installing.add_argument("--python", default="3.13", help="uv Python interpreter selector")
+    installing.add_argument("--bin-dir", default="~/.local/bin")
+    installing.add_argument(
+        "--timeout", type=float, default=600, help="seconds per update operation"
+    )
+    updating = commands.add_parser("update", help="check and atomically activate an update")
+    updating.add_argument("name")
+    updating.add_argument("--background", action="store_true", help=argparse.SUPPRESS)
+    inspecting = commands.add_parser("status", help="show the active installation and last check")
+    inspecting.add_argument("name")
+    args = parser.parse_args(argv)
+    logging.basicConfig(level=logging.INFO, format="uv-launch: %(message)s")
+    try:
+        if args.command == "install":
+            if args.timeout <= 0:
+                raise ValueError("timeout must be positive")
+            result = install(args)
+        elif args.command == "update":
+            result = update(args.name, background=args.background)
+        else:
+            root = tool_directory(args.name)
+            result = {
+                "config": json.loads((root / "current/config.json").read_text()),
+                "active": json.loads((root / "current/installation.json").read_text()),
+                "last_update": json.loads((root / "last-update.json").read_text())
+                if (root / "last-update.json").exists()
+                else None,
+            }
+        if not getattr(args, "background", False):
+            sys.stdout.write(json.dumps(result, sort_keys=True) + "\n")
+        return 0
+    except (OSError, ValueError, subprocess.SubprocessError) as error:
+        LOGGER.error("%s", error)
+        return 1

uv_launch-0.1.1/src/uv_launch/__main__.py

@@ -0,0 +1,3 @@
+from uv_launch import main
+
+raise SystemExit(main())