uv-launch 0.2.0__tar.gz → 0.2.2__tar.gz

{uv_launch-0.2.0 → uv_launch-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: uv-launch
-Version: 0.2.0
+Version: 0.2.2
 Summary: Immediate Python command startup with atomic background updates through uv
 Requires-Dist: packaging>=24
 Requires-Python: >=3.11
@@ -11,7 +11,7 @@ Description-Content-Type: text/markdown
 
 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:
+Requires macOS or Linux, Python 3.11+, and [uv](https://docs.astral.sh/uv/). Use `uvx uv-launch` from [PyPI](https://pypi.org/project/uv-launch/) to install commands without maintaining a bootstrap environment. A stable `uv tool install uv-launch` also works. Each managed application includes its own updater, so later launches do not depend on the bootstrap interpreter. Then install commands:
 
 ```sh
 uv-launch install ruff ruff
@@ -28,7 +28,21 @@ Each invocation captures the current immutable generation and starts a detached
 
 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`.
+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. The updater is resolved with the application and runs from the captured generation. A successful update can therefore deliver a newer updater as well as newer application code. Existing installations created before 0.2.1 need one reinstall to adopt this behavior.
+
+## Source toolfuncs
+
+Install a standalone toolfunc together with its adjacent repository files:
+
+```sh
+uvx uv-launch install-source wiki https://github.com/owner/wiki scripts/wiki --prepare prepare-runtime
+```
+
+`SOURCE` must be a repository-relative PEP 723 toolfunc whose filename matches the command. `--revision` defaults to `main`; `--with`, `--python`, `--bin-dir` and `--timeout` work as for package installations. Put `--prepare` last: its remaining arguments invoke a candidate's toolfunc to prepare and validate application-specific integrations before activation.
+
+Each check fetches one exact Git revision and resolves the script's declared dependencies together with toolfuncs and uv-launch. It validates the prepared tool and optional preparation command, then selects the complete generation atomically. Source-only changes reuse the same immutable dependency environment. Running commands keep their captured source and interpreter; failed builds and offline checks keep the last successful installation.
+
+The foreground calls `toolfuncs run-prepared`, which loads the selected source in its already prepared environment. It does not resolve or install another environment. `managed_target` resolves a source installation to its executable source for static discovery. The source repository is delivery state; applications should keep mutable user work elsewhere.
 
 ## Service startup and companion commands
 

{uv_launch-0.2.0 → uv_launch-0.2.2}/README.md

@@ -2,7 +2,7 @@
 
 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:
+Requires macOS or Linux, Python 3.11+, and [uv](https://docs.astral.sh/uv/). Use `uvx uv-launch` from [PyPI](https://pypi.org/project/uv-launch/) to install commands without maintaining a bootstrap environment. A stable `uv tool install uv-launch` also works. Each managed application includes its own updater, so later launches do not depend on the bootstrap interpreter. Then install commands:
 
 ```sh
 uv-launch install ruff ruff
@@ -19,7 +19,21 @@ Each invocation captures the current immutable generation and starts a detached
 
 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`.
+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. The updater is resolved with the application and runs from the captured generation. A successful update can therefore deliver a newer updater as well as newer application code. Existing installations created before 0.2.1 need one reinstall to adopt this behavior.
+
+## Source toolfuncs
+
+Install a standalone toolfunc together with its adjacent repository files:
+
+```sh
+uvx uv-launch install-source wiki https://github.com/owner/wiki scripts/wiki --prepare prepare-runtime
+```
+
+`SOURCE` must be a repository-relative PEP 723 toolfunc whose filename matches the command. `--revision` defaults to `main`; `--with`, `--python`, `--bin-dir` and `--timeout` work as for package installations. Put `--prepare` last: its remaining arguments invoke a candidate's toolfunc to prepare and validate application-specific integrations before activation.
+
+Each check fetches one exact Git revision and resolves the script's declared dependencies together with toolfuncs and uv-launch. It validates the prepared tool and optional preparation command, then selects the complete generation atomically. Source-only changes reuse the same immutable dependency environment. Running commands keep their captured source and interpreter; failed builds and offline checks keep the last successful installation.
+
+The foreground calls `toolfuncs run-prepared`, which loads the selected source in its already prepared environment. It does not resolve or install another environment. `managed_target` resolves a source installation to its executable source for static discovery. The source repository is delivery state; applications should keep mutable user work elsewhere.
 
 ## Service startup and companion commands
 

{uv_launch-0.2.0 → uv_launch-0.2.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "uv-launch"
-version = "0.2.0"
+version = "0.2.2"
 description = "Immediate Python command startup with atomic background updates through uv"
 readme = "README.md"
 requires-python = ">=3.11"

{uv_launch-0.2.0 → uv_launch-0.2.2}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "uv-launch"
-version = "0.2.0"
+version = "0.2.2"
 description = "Immediate Python command startup with atomic background updates through uv"
 readme = "README.md"
 requires-python = ">=3.11"

{uv_launch-0.2.0 → uv_launch-0.2.2}/src/uv_launch/__init__.py

@@ -53,9 +53,7 @@ def _run_checked(arguments: list[str], **kwargs) -> None:
 
 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()
-    )
+    return Path(os.environ.get("UV_LAUNCH_HOME", "~/.local/share/uv-launch")).expanduser().resolve()
 
 
 def tool_directory(name: str) -> Path:
@@ -102,6 +100,10 @@ def run_uv(config: dict, arguments: list[str], *, cwd: Path) -> None:
 
 def refresh(root: Path, config: dict) -> dict:
     """Prepare an immutable candidate; publish only after dependency and entrypoint checks."""
+    if config.get("kind") == "source":
+        from .source import refresh_source
+
+        return refresh_source(root, config)
     generations = root / "generations"
     generations.mkdir(exist_ok=True)
     candidate = generations / uuid.uuid4().hex
@@ -209,10 +211,14 @@ def refresh(root: Path, config: dict) -> dict:
 
 
 def _launcher_content(root: Path, config: dict, manager_python: str) -> str:
-    python = shlex.quote(manager_python)
     home = shlex.quote(str(root.parent))
     name = shlex.quote(config["name"])
     directory = shlex.quote(str(root))
+    python = (
+        f'{directory}/"$generation"/venv/bin/python'
+        if config.get("managed_updater")
+        else shlex.quote(manager_python)
+    )
     return (
         "#!/bin/sh\n"
         f"# Managed by uv-launch: {config['name']}\n"
@@ -254,7 +260,10 @@ def install(args: argparse.Namespace) -> dict:
         "uv": uv,
         "timeout": args.timeout,
         "bin_dir": str(Path(args.bin_dir).expanduser().absolute()),
+        "managed_updater": True,
     }
+    if args.name != "uv-launch":
+        config["requirements"].append("uv-launch>=0.2.1,<0.3")
     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")
@@ -344,6 +353,10 @@ def execute_installation(
         raise ValueError("installation identity does not match its generation")
     config = json.loads((generation / "config.json").read_text())
     selected = command or config["entrypoint"]
+    if config.get("kind") == "source" and command is None:
+        executable = generation / "command"
+        os.execv(str(executable), [str(executable), *arguments])
+        raise AssertionError("exec returned")
     tool_directory(selected)
     executable = generation / "venv/bin" / selected
     if not executable.is_file() or not os.access(executable, os.X_OK):
@@ -367,6 +380,22 @@ def main(argv: list[str] | None = None) -> int:
     installing.add_argument(
         "--timeout", type=float, default=600, help="seconds per update operation"
     )
+    source_installing = commands.add_parser(
+        "install-source", help="install a toolfunc and adjacent files from a Git repository"
+    )
+    source_installing.add_argument("name", help="toolfunc executable name")
+    source_installing.add_argument("repository", help="Git remote URL or local repository")
+    source_installing.add_argument("source", help="repository-relative toolfunc path")
+    source_installing.add_argument("--revision", default="main", help="branch, tag, or commit")
+    source_installing.add_argument("--with", dest="extra", action="append", default=[])
+    source_installing.add_argument("--python", default="3.13")
+    source_installing.add_argument("--bin-dir", default="~/.local/bin")
+    source_installing.add_argument("--timeout", type=float, default=600)
+    source_installing.add_argument(
+        "--prepare",
+        nargs=argparse.REMAINDER,
+        help="toolfunc arguments to prepare and validate a candidate before activation",
+    )
     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)
@@ -395,6 +424,10 @@ def main(argv: list[str] | None = None) -> int:
             if args.timeout <= 0:
                 raise ValueError("timeout must be positive")
             result = install(args)
+        elif args.command == "install-source":
+            from .source import install_source
+
+            result = install_source(args)
         elif args.command == "update":
             result = update(args.name, background=args.background)
         elif args.command == "select":

{uv_launch-0.2.0 → uv_launch-0.2.2}/src/uv_launch/dependencies.py

@@ -331,7 +331,16 @@ def managed_target(source: Path) -> Path | None:
     config = json.loads((generation / "config.json").read_text())
     if source.read_text() != _launcher_content(root, config, manager_python):
         raise ValueError("managed launcher content does not match its installation")
+    if config.get("kind") == "source":
+        from .source import source_command
+
+        if (generation / "command").read_text() != source_command(generation, config):
+            raise ValueError("managed source command does not match its installation")
+        target = (generation / "source" / config["source"]).resolve(strict=True)
+        if not target.is_relative_to(generation / "source"):
+            raise ValueError("managed source must belong to its generation")
+        return target
     target = (generation / "command").resolve(strict=True)
-    if not target.is_relative_to(generation / "venv"):
+    if not target.is_relative_to((generation / "venv").resolve()):
         raise ValueError("managed command must belong to its generation")
     return target

uv_launch-0.2.2/src/uv_launch/source.py

@@ -0,0 +1,231 @@
+"""Immutable Git source applications with prepared toolfunc environments."""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import os
+import re
+import shlex
+import shutil
+import subprocess
+import time
+import tomllib
+import uuid
+from pathlib import Path
+
+from . import _run_checked, atomic_write, installation_lock, run_uv, tool_directory, write_launcher
+
+
+def _git(config: dict, *arguments: str, cwd: Path) -> str:
+    return subprocess.check_output(
+        ["git", *arguments],
+        cwd=cwd,
+        text=True,
+        stdin=subprocess.DEVNULL,
+        stderr=subprocess.PIPE,
+        timeout=config["timeout"],
+    ).strip()
+
+
+def _script_metadata(source: Path) -> dict:
+    blocks = re.findall(r"(?m)^# /// script\s*\n((?:#(?: .*|)\n)+)# ///\s*$", source.read_text())
+    if len(blocks) != 1:
+        raise ValueError(f"{source}: expected one PEP 723 script block")
+    metadata = tomllib.loads("\n".join(line[2:] for line in blocks[0].splitlines()))
+    if not isinstance(metadata.get("dependencies"), list):
+        raise ValueError(f"{source}: script dependencies must be a list")
+    return metadata
+
+
+def source_command(generation: Path, config: dict) -> str:
+    """Render the exact executable boundary for a prepared source generation."""
+    return (
+        "#!/bin/sh\n"
+        f"export UV_LAUNCH_GENERATION={shlex.quote(str(generation))}\n"
+        f"exec {shlex.quote(str(generation / 'venv/bin/python'))} -I -m toolfuncs "
+        f'run-prepared {shlex.quote(str(generation / "source" / config["source"]))} "$@"\n'
+    )
+
+
+def refresh_source(root: Path, config: dict) -> dict:
+    """Fetch and validate a complete candidate without changing any selected generation."""
+    cache = root / "repository.git"
+    if not cache.exists():
+        _git(config, "init", "--bare", str(cache), cwd=root)
+    _git(config, "fetch", "--no-tags", config["repository"], config["revision"], cwd=cache)
+    revision = _git(config, "rev-parse", "FETCH_HEAD^{commit}", cwd=cache)
+    generations = root / "generations"
+    generations.mkdir(exist_ok=True)
+    candidate = generations / uuid.uuid4().hex
+    candidate.mkdir(mode=0o700)
+    published = False
+    try:
+        source_root = candidate / "source"
+        _git(
+            config,
+            "clone",
+            "--local",
+            "--no-hardlinks",
+            "--no-checkout",
+            str(cache),
+            str(source_root),
+            cwd=root,
+        )
+        _git(config, "checkout", "-B", "main", revision, cwd=source_root)
+        _git(config, "remote", "set-url", "origin", config["repository"], cwd=source_root)
+        source = (source_root / config["source"]).resolve(strict=True)
+        if not source.is_relative_to(source_root):
+            raise ValueError("toolfunc source must stay inside its repository")
+        metadata = _script_metadata(source)
+        requirements = candidate / "requirements.in"
+        requirements.write_text(
+            "\n".join(
+                [
+                    "toolfuncs>=0.12.1,<0.13",
+                    "uv-launch>=0.2.1,<0.3",
+                    *metadata["dependencies"],
+                    *config["extra"],
+                ]
+            )
+            + "\n"
+        )
+        lock = candidate / "requirements.txt"
+        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" + revision + "\n" + lock.read_text()
+            ).encode()
+        ).hexdigest()
+        if (root / "current").exists():
+            previous = json.loads((root / "current/installation.json").read_text())
+            if previous["identity"] == identity:
+                return {"status": "unchanged", **previous}
+
+        # Source-only updates share an immutable environment. Never relocate venvs.
+        environment_id = hashlib.sha256(
+            (config["python"] + "\n" + lock.read_text()).encode()
+        ).hexdigest()
+        environment_root = root / "environments" / environment_id
+        environment = environment_root / "venv"
+        if not (environment_root / "ready").exists():
+            if environment_root.exists():
+                shutil.rmtree(environment_root)
+            environment_root.mkdir(parents=True)
+            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,
+            )
+            (environment_root / "ready").touch()
+        (candidate / "venv").symlink_to(environment)
+        python = str(environment / "bin/python")
+        _run_checked(
+            [
+                python,
+                "-I",
+                "-m",
+                "toolfuncs",
+                "doctor",
+                "--prepared",
+                str(source),
+            ],
+            cwd=source_root,
+            stdin=subprocess.DEVNULL,
+            stdout=subprocess.DEVNULL,
+            timeout=config["timeout"],
+        )
+        atomic_write(candidate / "command", source_command(candidate, config), 0o755)
+        if config["prepare"]:
+            _run_checked(
+                [str(candidate / "command"), *config["prepare"]],
+                cwd=source_root,
+                stdin=subprocess.DEVNULL,
+                stdout=subprocess.DEVNULL,
+                timeout=config["timeout"],
+            )
+        record = {
+            "identity": identity,
+            "generation": str(candidate),
+            "revision": revision,
+            "created_at": time.time(),
+        }
+        atomic_write(candidate / "installation.json", json.dumps(record, sort_keys=True))
+        atomic_write(candidate / "config.json", json.dumps(config, indent=2) + "\n")
+        link = root / f".current-{uuid.uuid4().hex}"
+        try:
+            link.symlink_to(candidate.relative_to(root), target_is_directory=True)
+            os.replace(link, root / "current")
+        finally:
+            link.unlink(missing_ok=True)
+        published = True
+        return {"status": "updated", **record}
+    finally:
+        if not published:
+            shutil.rmtree(candidate)
+
+
+def install_source(args: argparse.Namespace) -> dict:
+    """Install a named Git source toolfunc with one automatically updated runtime."""
+    root = tool_directory(args.name)
+    source = Path(args.source)
+    if source.is_absolute() or ".." in source.parts or source.name != args.name:
+        raise ValueError("source must be a repository-relative path with the command's name")
+    if args.timeout <= 0:
+        raise ValueError("timeout must be positive")
+    uv = shutil.which("uv")
+    if uv is None:
+        raise ValueError("uv must be installed and available on PATH")
+    repository = args.repository
+    if Path(repository).exists():
+        repository = str(Path(repository).resolve())
+    config = {
+        "kind": "source",
+        "name": args.name,
+        "entrypoint": args.name,
+        "repository": repository,
+        "revision": args.revision,
+        "source": str(source),
+        "extra": args.extra,
+        "python": args.python,
+        "uv": uv,
+        "timeout": args.timeout,
+        "bin_dir": str(Path(args.bin_dir).expanduser().absolute()),
+        "prepare": args.prepare or [],
+        "managed_updater": True,
+    }
+    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_source(root, config)
+        destination = write_launcher(root, config)
+    return {**result, "command": str(destination)}