PyPI - uv-launch - Versions diffs - 0.2.2__tar.gz → 0.2.4__tar.gz - Mend

uv-launch 0.2.2tar.gz → 0.2.4tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (11) hide show

uv_launch-0.2.4/PKG-INFO +139 -0
uv_launch-0.2.4/README.md +129 -0
{uv_launch-0.2.2 → uv_launch-0.2.4}/pyproject.toml +5 -2
{uv_launch-0.2.2 → uv_launch-0.2.4}/pyproject.toml.orig +2 -2
{uv_launch-0.2.2 → uv_launch-0.2.4}/src/uv_launch/__init__.py +362 -57
{uv_launch-0.2.2 → uv_launch-0.2.4}/src/uv_launch/dependencies.py +23 -2
uv_launch-0.2.2/PKG-INFO +0 -103
uv_launch-0.2.2/README.md +0 -94
{uv_launch-0.2.2 → uv_launch-0.2.4}/src/uv_launch/__main__.py +0 -0
{uv_launch-0.2.2 → uv_launch-0.2.4}/src/uv_launch/py.typed +0 -0
{uv_launch-0.2.2 → uv_launch-0.2.4}/src/uv_launch/source.py +0 -0

uv_launch-0.2.4/PKG-INFO ADDED Viewed

@@ -0,0 +1,139 @@
+Metadata-Version: 2.3
+Name: uv-launch
+Version: 0.2.4
+Summary: Immediate Python command startup with atomic background updates through uv
+Requires-Dist: packaging>=24
+Requires-Dist: platformdirs>=4.8
+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/). 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
+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
+```
+Directory defaults come from [platformdirs](https://platformdirs.readthedocs.io/en/latest/api.html): `user_bin_path()` for installed commands and `user_data_path("uv-launch", appauthor=False)` for durable installations. On macOS the data directory is `~/Library/Application Support/uv-launch`; on Linux it follows `XDG_DATA_HOME`, normally `~/.local/share/uv-launch`. Both platforms normally install commands in `~/.local/bin`. `--bin-dir` and a nonempty `UV_LAUNCH_HOME` override those defaults. Use a separate directory for evaluation. The installer refuses to overwrite commands it does not own.
+To adopt the platform directory after upgrading from 0.2.2 or earlier, repeat the original `install` or `install-source` command with its existing requirements and options, without a `UV_LAUNCH_HOME` override. This builds and validates a new installation before replacing its launcher. Keep the old directory while any process uses it; do not move its virtual environments, whose executable paths are absolute. Existing launchers retain their recorded directory until reinstalled. To operate on an old installation directly, set `UV_LAUNCH_HOME` to its recorded root.
+Each invocation without an explicit generation pin 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), runs any configured validation command, 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, with a configured generation variable set to the selected ID. 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`. Without `--validate`, validation checks installation and entrypoint integrity only. 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.
+## Package candidate validation
+An application can check its packaged resources, hooks, companion commands, and startup before a new generation becomes active:
+```sh
+uv-launch install my-command 'package-name @ git+https://github.com/owner/project.git@main' \
+  --entrypoint actual-console-script --validation-timeout 30 \
+  --validate package-check --smoke-test
+```
+Put `--validate` last. It takes the name of an executable in the candidate's `venv/bin` followed by fixed arguments, passed directly without a shell. The executable need not have a public shim. The command and timeout are saved in the installation and apply to initial installation, reinstall, foreground updates, and background updates. `--validation-timeout` defaults to 60 seconds and must be finite and positive. An unchanged generation does not run validation again.
+When validation is configured, entrypoint import checks and the validation command run with a fresh temporary working directory and clean environment. `HOME`, `XDG_CONFIG_HOME`, `XDG_DATA_HOME`, `XDG_STATE_HOME`, `XDG_CACHE_HOME`, `XDG_RUNTIME_DIR`, `XDG_CONFIG_DIRS`, `XDG_DATA_DIRS`, `TMPDIR`, and `UV_LAUNCH_HOME` point to private temporary directories, removed after the check. Application-specific environment variables and credentials are not inherited. `PATH` starts with the candidate's `venv/bin` and retains the calling process's PATH for external tools. `VIRTUAL_ENV` names the candidate environment, `UV_LAUNCH_GENERATION` gives its absolute generation directory, and a configured `--generation-env` variable contains its opaque generation ID. Dependency resolution still uses the user's normal uv/Git authentication. This isolates conventional configuration and state paths; it is not an operating-system sandbox against code that deliberately accesses other paths.
+A zero exit status permits the existing atomic activation. A nonzero exit, missing validation executable, or timeout rejects and removes the candidate while retaining the active generation and its shims. Timeout cleanup terminates the command's process group, allowing up to five seconds for the command to exit before forced termination. `uv-launch status my-command` exposes `last_validation`, including the attempted generation, command, `returncode` (null if it could not start or timed out), `timed_out`, `checked_at`, `duration_seconds`, and the final 8192 bytes of combined stdout/stderr decoded as UTF-8. The record is also stored in `<UV_LAUNCH_HOME>/<command>/last-validation.json`. A failed first validation is inspectable with `status`, with `active` and `config` set to null. Update failures also appear in `last_update`, and background failures in `update.log`.
+Repeat the original install command with the new options to enable validation for an existing installation. New package installations require uv-launch `>=0.2.4,<0.3` in their environments so the bundled updater understands these settings. Installations using validation, companions, or a generation pin use configuration schema 2, which stores `package_requirements` and omits the legacy `requirements` key. A 0.2.3 updater, including one that started before a reinstall, therefore fails before resolution instead of publishing a candidate without enforcing the new settings. The current updater still reads ordinary legacy configurations; refreshing an earlier unversioned configuration with these features rebuilds it in the protected format before activation.
+## 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
+Package installations can expose selected companion console scripts alongside the main command:
+```sh
+uv-launch install my-command package-name --entrypoint actual-console-script \
+  --companion package-helper --companion package-admin \
+  --generation-env MY_APP_GENERATION \
+  --validate package-check --smoke-test
+```
+Each repeatable `--companion` names a candidate executable and creates a shim of that name in `--bin-dir`. Main and companion entrypoints are checked before activation; unrelated commands are never overwritten. All shims select from the same installation, so they switch together on an update. `--companion` and `--generation-env` are package-mode options.
+Reinstalling without a previously selected companion retires it only after the new candidate succeeds. If no generation variable was configured, its owned shim is removed. Otherwise the shim remains available for pinned sessions: unpinned calls report that it is retired, while an explicit pin still runs the executable from that retained generation. A retired shim continues to use the variable configured before retirement, even if the reinstall changes or omits `--generation-env`. Retirement records persist across updates and reinstalls; selecting the companion again restores normal dispatch. User-owned replacements are preserved, and rejected reinstalls preserve both the active generation and its shims. Retired shims and old generations can be removed manually once no sessions use them.
+With `--generation-env MY_APP_GENERATION`, every active shim exports its captured generation ID in that variable. Child shells and companion commands inherit the pin, even if shell startup files put the global shim directory first on PATH. A nonempty pin must name an existing generation of this installation; invalid or unavailable pins fail instead of switching to the active generation. An unset or empty pin selects the current generation and starts the usual background update check. Explicitly pinned launches do not start an updater from the old runtime. Use a distinct application-specific variable name, such as `MY_APP_GENERATION`. Standard configuration and launcher variables, shell-managed names such as `PPID`, `IFS`, `UID`, `EUID`, and `RANDOM`, and the `BASH*` and `COMP_*` namespaces are rejected. Old generations are retained, so an update cannot retarget a running session. `managed_target` also honors the pin when inspecting main, companion, and retired shims; inspecting an unpinned retired shim reports retirement.
+A service can require the latest successfully resolved dependencies at startup:
+```sh
+uv-launch run --refresh my-command -- serve --port 8080
+```
+Unlike the ordinary background-updating shim, `run --refresh` waits for a successful update and fails without executing stale code when that update fails. It then replaces itself with the selected command. Arguments, environment, working directory and exit status are preserved. SIGTERM during refresh terminates and reaps the resolver/build process group; after execution the application receives signals directly. Old generations remain available for workers that outlive their launcher.
+Run a companion executable from the same installation with `uv-launch run --command python my-command -- -c 'print("probe")'`. Options to `run` precede the installation name. For several operations that must use exactly the same generation, capture once and pass the returned opaque `generation` value:
+```sh
+uv-launch select --refresh my-command
+uv-launch run --generation GENERATION --command python my-command -- -c 'print("probe")'
+uv-launch run --generation GENERATION my-command -- serve
+```
+The Python equivalents are `select_installation(name, refresh_dependencies=True)` and `execute_installation(installation, arguments, command=None)` from `uv_launch`. `execute_installation` uses `exec`, so successful execution does not return. `run` and `execute_installation` export a configured generation variable for the generation they explicitly select; `select` and `run` retain their explicit selection semantics rather than consulting the shim pin. The opaque `generation` returned by `select` can also be assigned to the configured variable when invoking a shim. Consumers should use these interfaces instead of reading installation symlinks or reconstructing generation paths.
+## Script runtimes and Python imports
+`uv_launch.dependencies` provides shared preparation for tools such as toolfuncs:
+- `prepare_environment(requirements, python=..., background=True)` returns a ready immutable virtual environment. Warm calls reuse a generation without foreground resolution; first use and changed requirements wait for preparation. It does not snapshot the caller's script.
+- `resolve_dependencies(requirements, python=..., constraints=(), background=True)` returns an immutable pinned requirements file. Resolutions are cached by requirements, interpreter/platform and constraints.
+- `install_dependencies(requirements)` adds missing packages to the **current interpreter's environment**. It reuses satisfying installed dependencies, constrains resolution to preserve existing distributions, checks the selected graph before installation, and raises `DependencyConflictError` if preservation is impossible. It never synchronizes the whole environment or replaces existing distributions. Background resolution refresh does not install into the active interpreter or reload modules.
+- `managed_target(path)` statically resolves a generated uv-launch command to its installed executable. It validates the shim against its recorded installation without executing shell code, importing the application, or requesting an update. This lets discovery tools inspect package metadata behind managed commands.
+The shared resolver accepts floating Git branches and records exact commit IDs in each cached resolution. No separate script registration or checked-in lockfile is required. A process already using an installed package retains that package; a new cached resolution is not a hot reload. Use a compatible environment when requirements conflict. Each installed source distribution is identified by its recorded origin or package version via `distribution_requirement(distribution)`.
+## 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 ./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, isolated candidate validation and its failure diagnostics, companion generation pins and retirement, failed updates, concurrent checks, offline launches, and preservation of unrelated commands. A frozen copy of the 0.2.3 updater exercises updates delayed across a reinstall. Shell tests cover dash and bash when installed, including unset, empty, valid, invalid, and unavailable pins and reserved generation-variable names.

uv_launch-0.2.4/README.md ADDED Viewed

@@ -0,0 +1,129 @@
+# 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/). 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
+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
+```
+Directory defaults come from [platformdirs](https://platformdirs.readthedocs.io/en/latest/api.html): `user_bin_path()` for installed commands and `user_data_path("uv-launch", appauthor=False)` for durable installations. On macOS the data directory is `~/Library/Application Support/uv-launch`; on Linux it follows `XDG_DATA_HOME`, normally `~/.local/share/uv-launch`. Both platforms normally install commands in `~/.local/bin`. `--bin-dir` and a nonempty `UV_LAUNCH_HOME` override those defaults. Use a separate directory for evaluation. The installer refuses to overwrite commands it does not own.
+To adopt the platform directory after upgrading from 0.2.2 or earlier, repeat the original `install` or `install-source` command with its existing requirements and options, without a `UV_LAUNCH_HOME` override. This builds and validates a new installation before replacing its launcher. Keep the old directory while any process uses it; do not move its virtual environments, whose executable paths are absolute. Existing launchers retain their recorded directory until reinstalled. To operate on an old installation directly, set `UV_LAUNCH_HOME` to its recorded root.
+Each invocation without an explicit generation pin 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), runs any configured validation command, 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, with a configured generation variable set to the selected ID. 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`. Without `--validate`, validation checks installation and entrypoint integrity only. 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.
+## Package candidate validation
+An application can check its packaged resources, hooks, companion commands, and startup before a new generation becomes active:
+```sh
+uv-launch install my-command 'package-name @ git+https://github.com/owner/project.git@main' \
+  --entrypoint actual-console-script --validation-timeout 30 \
+  --validate package-check --smoke-test
+```
+Put `--validate` last. It takes the name of an executable in the candidate's `venv/bin` followed by fixed arguments, passed directly without a shell. The executable need not have a public shim. The command and timeout are saved in the installation and apply to initial installation, reinstall, foreground updates, and background updates. `--validation-timeout` defaults to 60 seconds and must be finite and positive. An unchanged generation does not run validation again.
+When validation is configured, entrypoint import checks and the validation command run with a fresh temporary working directory and clean environment. `HOME`, `XDG_CONFIG_HOME`, `XDG_DATA_HOME`, `XDG_STATE_HOME`, `XDG_CACHE_HOME`, `XDG_RUNTIME_DIR`, `XDG_CONFIG_DIRS`, `XDG_DATA_DIRS`, `TMPDIR`, and `UV_LAUNCH_HOME` point to private temporary directories, removed after the check. Application-specific environment variables and credentials are not inherited. `PATH` starts with the candidate's `venv/bin` and retains the calling process's PATH for external tools. `VIRTUAL_ENV` names the candidate environment, `UV_LAUNCH_GENERATION` gives its absolute generation directory, and a configured `--generation-env` variable contains its opaque generation ID. Dependency resolution still uses the user's normal uv/Git authentication. This isolates conventional configuration and state paths; it is not an operating-system sandbox against code that deliberately accesses other paths.
+A zero exit status permits the existing atomic activation. A nonzero exit, missing validation executable, or timeout rejects and removes the candidate while retaining the active generation and its shims. Timeout cleanup terminates the command's process group, allowing up to five seconds for the command to exit before forced termination. `uv-launch status my-command` exposes `last_validation`, including the attempted generation, command, `returncode` (null if it could not start or timed out), `timed_out`, `checked_at`, `duration_seconds`, and the final 8192 bytes of combined stdout/stderr decoded as UTF-8. The record is also stored in `<UV_LAUNCH_HOME>/<command>/last-validation.json`. A failed first validation is inspectable with `status`, with `active` and `config` set to null. Update failures also appear in `last_update`, and background failures in `update.log`.
+Repeat the original install command with the new options to enable validation for an existing installation. New package installations require uv-launch `>=0.2.4,<0.3` in their environments so the bundled updater understands these settings. Installations using validation, companions, or a generation pin use configuration schema 2, which stores `package_requirements` and omits the legacy `requirements` key. A 0.2.3 updater, including one that started before a reinstall, therefore fails before resolution instead of publishing a candidate without enforcing the new settings. The current updater still reads ordinary legacy configurations; refreshing an earlier unversioned configuration with these features rebuilds it in the protected format before activation.
+## 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
+Package installations can expose selected companion console scripts alongside the main command:
+```sh
+uv-launch install my-command package-name --entrypoint actual-console-script \
+  --companion package-helper --companion package-admin \
+  --generation-env MY_APP_GENERATION \
+  --validate package-check --smoke-test
+```
+Each repeatable `--companion` names a candidate executable and creates a shim of that name in `--bin-dir`. Main and companion entrypoints are checked before activation; unrelated commands are never overwritten. All shims select from the same installation, so they switch together on an update. `--companion` and `--generation-env` are package-mode options.
+Reinstalling without a previously selected companion retires it only after the new candidate succeeds. If no generation variable was configured, its owned shim is removed. Otherwise the shim remains available for pinned sessions: unpinned calls report that it is retired, while an explicit pin still runs the executable from that retained generation. A retired shim continues to use the variable configured before retirement, even if the reinstall changes or omits `--generation-env`. Retirement records persist across updates and reinstalls; selecting the companion again restores normal dispatch. User-owned replacements are preserved, and rejected reinstalls preserve both the active generation and its shims. Retired shims and old generations can be removed manually once no sessions use them.
+With `--generation-env MY_APP_GENERATION`, every active shim exports its captured generation ID in that variable. Child shells and companion commands inherit the pin, even if shell startup files put the global shim directory first on PATH. A nonempty pin must name an existing generation of this installation; invalid or unavailable pins fail instead of switching to the active generation. An unset or empty pin selects the current generation and starts the usual background update check. Explicitly pinned launches do not start an updater from the old runtime. Use a distinct application-specific variable name, such as `MY_APP_GENERATION`. Standard configuration and launcher variables, shell-managed names such as `PPID`, `IFS`, `UID`, `EUID`, and `RANDOM`, and the `BASH*` and `COMP_*` namespaces are rejected. Old generations are retained, so an update cannot retarget a running session. `managed_target` also honors the pin when inspecting main, companion, and retired shims; inspecting an unpinned retired shim reports retirement.
+A service can require the latest successfully resolved dependencies at startup:
+```sh
+uv-launch run --refresh my-command -- serve --port 8080
+```
+Unlike the ordinary background-updating shim, `run --refresh` waits for a successful update and fails without executing stale code when that update fails. It then replaces itself with the selected command. Arguments, environment, working directory and exit status are preserved. SIGTERM during refresh terminates and reaps the resolver/build process group; after execution the application receives signals directly. Old generations remain available for workers that outlive their launcher.
+Run a companion executable from the same installation with `uv-launch run --command python my-command -- -c 'print("probe")'`. Options to `run` precede the installation name. For several operations that must use exactly the same generation, capture once and pass the returned opaque `generation` value:
+```sh
+uv-launch select --refresh my-command
+uv-launch run --generation GENERATION --command python my-command -- -c 'print("probe")'
+uv-launch run --generation GENERATION my-command -- serve
+```
+The Python equivalents are `select_installation(name, refresh_dependencies=True)` and `execute_installation(installation, arguments, command=None)` from `uv_launch`. `execute_installation` uses `exec`, so successful execution does not return. `run` and `execute_installation` export a configured generation variable for the generation they explicitly select; `select` and `run` retain their explicit selection semantics rather than consulting the shim pin. The opaque `generation` returned by `select` can also be assigned to the configured variable when invoking a shim. Consumers should use these interfaces instead of reading installation symlinks or reconstructing generation paths.
+## Script runtimes and Python imports
+`uv_launch.dependencies` provides shared preparation for tools such as toolfuncs:
+- `prepare_environment(requirements, python=..., background=True)` returns a ready immutable virtual environment. Warm calls reuse a generation without foreground resolution; first use and changed requirements wait for preparation. It does not snapshot the caller's script.
+- `resolve_dependencies(requirements, python=..., constraints=(), background=True)` returns an immutable pinned requirements file. Resolutions are cached by requirements, interpreter/platform and constraints.
+- `install_dependencies(requirements)` adds missing packages to the **current interpreter's environment**. It reuses satisfying installed dependencies, constrains resolution to preserve existing distributions, checks the selected graph before installation, and raises `DependencyConflictError` if preservation is impossible. It never synchronizes the whole environment or replaces existing distributions. Background resolution refresh does not install into the active interpreter or reload modules.
+- `managed_target(path)` statically resolves a generated uv-launch command to its installed executable. It validates the shim against its recorded installation without executing shell code, importing the application, or requesting an update. This lets discovery tools inspect package metadata behind managed commands.
+The shared resolver accepts floating Git branches and records exact commit IDs in each cached resolution. No separate script registration or checked-in lockfile is required. A process already using an installed package retains that package; a new cached resolution is not a hot reload. Use a compatible environment when requirements conflict. Each installed source distribution is identified by its recorded origin or package version via `distribution_requirement(distribution)`.
+## 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 ./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, isolated candidate validation and its failure diagnostics, companion generation pins and retirement, failed updates, concurrent checks, offline launches, and preservation of unrelated commands. A frozen copy of the 0.2.3 updater exercises updates delayed across a reinstall. Shell tests cover dash and bash when installed, including unset, empty, valid, invalid, and unavailable pins and reserved generation-variable names.

{uv_launch-0.2.2 → uv_launch-0.2.4}/pyproject.toml RENAMED Viewed

@@ -1,10 +1,13 @@
 [project]
 name = "uv-launch"
-version = "0.2.2"
+version = "0.2.4"
 description = "Immediate Python command startup with atomic background updates through uv"
 readme = "README.md"
 requires-python = ">=3.11"
-dependencies = ["packaging>=24"]
+dependencies = [
+    "packaging>=24",
+    "platformdirs>=4.8",
+]
 [project.urls]
 Repository = "https://github.com/nimashoghi/uv-launch"

{uv_launch-0.2.2 → uv_launch-0.2.4}/pyproject.toml.orig RENAMED Viewed

@@ -1,10 +1,10 @@
 [project]
 name = "uv-launch"
-version = "0.2.2"
+version = "0.2.4"
 description = "Immediate Python command startup with atomic background updates through uv"
 readme = "README.md"
 requires-python = ">=3.11"
-dependencies = ["packaging>=24"]
+dependencies = ["packaging>=24", "platformdirs>=4.8"]
 [project.urls]
 Repository = "https://github.com/nimashoghi/uv-launch"

{uv_launch-0.2.2 → uv_launch-0.2.4}/src/uv_launch/__init__.py RENAMED Viewed

@@ -7,6 +7,7 @@ import fcntl
 import hashlib
 import json
 import logging
+import math
 import os
 import re
 import shlex
@@ -17,11 +18,74 @@ import sys
 import tempfile
 import time
 import uuid
-from contextlib import contextmanager
+from contextlib import contextmanager, suppress
 from dataclasses import asdict, dataclass
 from pathlib import Path
+from platformdirs import user_bin_path, user_data_path
 LOGGER = logging.getLogger(__name__)
+_ISOLATED_DIRECTORIES = (
+    "HOME",
+    "XDG_CONFIG_HOME",
+    "XDG_DATA_HOME",
+    "XDG_STATE_HOME",
+    "XDG_CACHE_HOME",
+    "XDG_RUNTIME_DIR",
+    "XDG_CONFIG_DIRS",
+    "XDG_DATA_DIRS",
+    "TMPDIR",
+    "UV_LAUNCH_HOME",
+)
+# Shell Variables in the Bash manual; these may be initialized, rewritten, or
+# readonly even when absent from the caller's environment. Reserve BASH*/COMP_*
+# below as namespaces so additions there cannot become generation variables.
+_SHELL_VARIABLES = frozenset(
+    [
+        "_",
+        "CDPATH",
+        "ENV",
+        "IFS",
+        "PPID",
+        "UID",
+        "EUID",
+        "PWD",
+        "OLDPWD",
+        "SHLVL",
+        "SHELL",
+        "SHELLOPTS",
+        "OPTARG",
+        "OPTERR",
+        "OPTIND",
+        "PS0",
+        "PS1",
+        "PS2",
+        "PS3",
+        "PS4",
+        "PROMPT_COMMAND",
+        "RANDOM",
+        "SRANDOM",
+        "SECONDS",
+        "EPOCHREALTIME",
+        "EPOCHSECONDS",
+        "LINENO",
+        "HISTCMD",
+        "GROUPS",
+        "DIRSTACK",
+        "PIPESTATUS",
+        "FUNCNAME",
+        "COPROC",
+        "COMPREPLY",
+        "MAPFILE",
+        "HOSTNAME",
+        "HOSTTYPE",
+        "MACHTYPE",
+        "OSTYPE",
+        "TERM",
+        "POSIXLY_CORRECT",
+        "GLOBIGNORE",
+    ]
+)
 class _Terminated(BaseException):
@@ -42,18 +106,22 @@ def _run_checked(arguments: list[str], **kwargs) -> None:
                 raise subprocess.CalledProcessError(returncode, arguments)
         except BaseException:
             if process.poll() is None:
-                os.killpg(process.pid, signal.SIGTERM)
-                try:
+                with suppress(ProcessLookupError):
+                    os.killpg(process.pid, signal.SIGTERM)
+                with suppress(subprocess.TimeoutExpired):
                     process.wait(timeout=5)
-                except subprocess.TimeoutExpired:
-                    os.killpg(process.pid, signal.SIGKILL)
-                    process.wait()
+            # Children may survive their parent or ignore SIGTERM.
+            with suppress(ProcessLookupError):
+                os.killpg(process.pid, signal.SIGKILL)
+            process.wait()
             raise
 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().resolve()
+    if override := os.environ.get("UV_LAUNCH_HOME"):
+        return Path(override).expanduser().resolve()
+    return user_data_path("uv-launch", appauthor=False).resolve()
 def tool_directory(name: str) -> Path:
@@ -98,12 +166,90 @@ def run_uv(config: dict, arguments: list[str], *, cwd: Path) -> None:
     )
+@contextmanager
+def _candidate_state(candidate: Path, config: dict):
+    if not config.get("validate"):
+        yield None, None
+        return
+    with tempfile.TemporaryDirectory(prefix="uv-launch-validation-") as temporary:
+        directory = Path(temporary)
+        # Start clean: inherited application-specific config paths and credentials
+        # must not bypass HOME/XDG isolation. This is not a filesystem sandbox.
+        environment = {
+            "PATH": str(candidate / "venv/bin") + os.pathsep + os.environ.get("PATH", os.defpath),
+            "VIRTUAL_ENV": str(candidate / "venv"),
+            "UV_LAUNCH_GENERATION": str(candidate),
+        }
+        for variable in _ISOLATED_DIRECTORIES:
+            path = directory / variable.lower()
+            path.mkdir(mode=0o700)
+            environment[variable] = str(path)
+        if variable := config.get("generation_env"):
+            environment[variable] = candidate.name
+        yield directory, environment
+def _validate_candidate(root: Path, candidate: Path, config: dict, *, cwd: Path, env: dict) -> None:
+    arguments = [str(candidate / "venv/bin" / config["validate"][0]), *config["validate"][1:]]
+    started = time.monotonic()
+    diagnostic = {
+        "command": config["validate"],
+        "generation": str(candidate),
+        "checked_at": time.time(),
+        "timeout": config["validation_timeout"],
+        "returncode": None,
+        "timed_out": False,
+    }
+    with tempfile.TemporaryFile() as output:
+        try:
+            _run_checked(
+                arguments,
+                cwd=cwd,
+                env=env,
+                stdin=subprocess.DEVNULL,
+                stdout=output,
+                stderr=subprocess.STDOUT,
+                timeout=config["validation_timeout"],
+            )
+        except (OSError, subprocess.SubprocessError) as error:
+            diagnostic.update(status="failed", error=str(error))
+            if isinstance(error, subprocess.CalledProcessError):
+                diagnostic["returncode"] = error.returncode
+            diagnostic["timed_out"] = isinstance(error, subprocess.TimeoutExpired)
+        else:
+            diagnostic.update(status="passed", returncode=0)
+        diagnostic["duration_seconds"] = time.monotonic() - started
+        output.seek(0, os.SEEK_END)
+        output.seek(max(0, output.tell() - 8192))
+        diagnostic["output_tail"] = output.read().decode("utf-8", errors="replace")
+    atomic_write(root / "last-validation.json", json.dumps(diagnostic))
+    if diagnostic["status"] == "failed":
+        raise ValueError(
+            f"candidate validation failed after {diagnostic['duration_seconds']:.3f}s: "
+            f"{diagnostic['error']}\n{diagnostic['output_tail']}"
+        )
 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)
+    if config.get("schema_version", 1) not in (1, 2):
+        raise ValueError("unsupported installation configuration version")
+    if "requirements" in config and any(
+        config.get(key)
+        for key in ("validate", "companions", "generation_env", "retired_companions")
+    ):
+        config = dict(config)
+        # 0.2.3 requires this legacy key before resolving or publishing. Removing
+        # it makes even an already-running old updater fail closed after reinstall.
+        config["package_requirements"] = config.pop("requirements")
+        config["schema_version"] = 2
+    package_requirements = config[
+        "package_requirements" if config.get("schema_version") == 2 else "requirements"
+    ]
     generations = root / "generations"
     generations.mkdir(exist_ok=True)
     candidate = generations / uuid.uuid4().hex
@@ -111,7 +257,7 @@ def refresh(root: Path, config: dict) -> dict:
     published = False
     try:
         requirements = candidate / "requirements.in"
-        requirements.write_text("\n".join(config["requirements"]) + "\n")
+        requirements.write_text("\n".join(package_requirements) + "\n")
         lock = candidate / "requirements.txt"
         constraints = candidate / "constraints.txt"
         constraints.write_text("\n".join(config.get("constraints", [])) + "\n")
@@ -168,30 +314,40 @@ def refresh(root: Path, config: dict) -> dict:
             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.
-        if config.get("entrypoint"):
-            _run_checked(
-                [
-                    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 executable owner'\n",
-                    config["entrypoint"],
-                    str(executable),
-                ],
-                stdin=subprocess.DEVNULL,
-                stdout=subprocess.DEVNULL,
-                timeout=config["timeout"],
-            )
+        with _candidate_state(candidate, config) as (validation_cwd, validation_env):
+            for entrypoint in dict.fromkeys([config["entrypoint"], *config.get("companions", [])]):
+                if not entrypoint:
+                    continue
+                companion = environment / "bin" / entrypoint
+                if not companion.is_file() or not os.access(companion, os.X_OK):
+                    raise ValueError(f"installed environment does not provide {entrypoint!r}")
+                _run_checked(
+                    [
+                        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 executable owner'\n",
+                        entrypoint,
+                        str(companion),
+                    ],
+                    cwd=validation_cwd,
+                    env=validation_env,
+                    stdin=subprocess.DEVNULL,
+                    stdout=subprocess.DEVNULL,
+                    timeout=config["timeout"],
+                )
+            if config.get("validate"):
+                _validate_candidate(root, candidate, config, cwd=validation_cwd, env=validation_env)
         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")
@@ -210,7 +366,12 @@ def refresh(root: Path, config: dict) -> dict:
             shutil.rmtree(candidate)
-def _launcher_content(root: Path, config: dict, manager_python: str) -> str:
+def _launcher_content(
+    root: Path, config: dict, manager_python: str, *, command: str | None = None
+) -> str:
+    retired = command in config.get("retired_companions", {})
+    if retired:
+        config = {**config, "generation_env": config["retired_companions"][command]}
     home = shlex.quote(str(root.parent))
     name = shlex.quote(config["name"])
     directory = shlex.quote(str(root))
@@ -219,28 +380,81 @@ def _launcher_content(root: Path, config: dict, manager_python: str) -> str:
         if config.get("managed_updater")
         else shlex.quote(manager_python)
     )
+    selection = f"generation=$(readlink {directory}/current) || exit 1\n"
+    update = (
+        f"UV_LAUNCH_HOME={home} nohup {python} -I -m uv_launch update {name} "
+        "--background </dev/null >/dev/null 2>&1 &\n"
+    )
+    export = ""
+    if variable := config.get("generation_env"):
+        selection = (
+            f'if [ -n "${{{variable}-}}" ]; then\n'
+            f'    generation="${variable}"\n'
+            '    case "$generation" in *[!a-f0-9]*) '
+            "echo 'uv-launch: invalid generation pin' >&2; exit 1;; esac\n"
+            '    [ "${#generation}" -eq 32 ] || { '
+            "echo 'uv-launch: invalid generation pin' >&2; exit 1; }\n"
+            '    generation="generations/$generation"\n'
+            f'    [ -f {directory}/"$generation"/installation.json ] || {{ '
+            "echo 'uv-launch: pinned generation is unavailable' >&2; exit 1; }\n"
+            f"else\n    {selection}fi\n"
+        )
+        # A pinned old updater may not understand settings added by a reinstall.
+        update = f'if [ -z "${{{variable}-}}" ]; then\n    {update}fi\n'
+        export = f'export {variable}="${{generation##*/}}"\n'
+        if retired:
+            error = shlex.quote(
+                f"uv-launch: companion {command!r} is retired; "
+                f"an explicit {variable} pin is required"
+            )
+            selection = (
+                f'if [ -z "${{{variable}-}}" ]; then echo {error} >&2; exit 1; fi\n' + selection
+            )
+    target = "command" if command is None else f"venv/bin/{command}"
+    check = ""
+    if retired:
+        error = shlex.quote(f"uv-launch: pinned generation does not provide {command!r}")
+        check = (
+            f'[ -x {directory}/"$generation"/{shlex.quote(target)} ] || '
+            f"{{ echo {error} >&2; exit 1; }}\n"
+        )
     return (
         "#!/bin/sh\n"
         f"# Managed by uv-launch: {config['name']}\n"
         f"# uv-launch-root: {json.dumps(str(root))}\n"
         f"# uv-launch-python: {json.dumps(manager_python)}\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'
+        f"{selection}"
+        f"{update}"
+        f"{export}"
+        f"{check}"
+        f'exec {directory}/"$generation"/{shlex.quote(target)} "$@"\n'
     )
-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)
-    content = _launcher_content(root, config, sys.executable)
-    if destination.exists() and not destination.read_text().startswith(
-        f"#!/bin/sh\n# Managed by uv-launch: {config['name']}\n"
+def _owned_launcher(path: Path, name: str) -> bool:
+    marker = f"#!/bin/sh\n# Managed by uv-launch: {name}\n".encode()
+    try:
+        with path.open("rb") as stream:
+            return stream.read(len(marker)) == marker
+    except OSError:
+        return False
+def _launcher_destination(config: dict, command: str | None = None) -> Path:
+    destination = Path(config["bin_dir"]) / (command or config["name"])
+    if (destination.exists() or destination.is_symlink()) and not _owned_launcher(
+        destination, config["name"]
     ):
         raise ValueError(f"refusing to replace an unmanaged command: {destination}")
+    return destination
+def write_launcher(root: Path, config: dict, *, command: str | None = None) -> Path:
+    """Install a shell shim with no foreground Python or package resolution overhead."""
+    destination = _launcher_destination(config, command)
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    content = _launcher_content(root, config, sys.executable, command=command)
     atomic_write(destination, content, 0o755)
     return destination
@@ -249,6 +463,28 @@ 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)
+    for companion in args.companion:
+        tool_directory(companion)
+        if companion == args.name:
+            raise ValueError("a companion command must differ from the launcher name")
+    if args.validate is not None:
+        if not args.validate:
+            raise ValueError("--validate requires a candidate command")
+        tool_directory(args.validate[0])
+    if args.generation_env is not None and (
+        not re.fullmatch(r"[A-Za-z_][A-Za-z0-9_]*", args.generation_env)
+        or args.generation_env in _SHELL_VARIABLES
+        or args.generation_env.startswith(("BASH", "COMP_"))
+        or args.generation_env
+        in {
+            "generation",
+            "PATH",
+            "VIRTUAL_ENV",
+            "UV_LAUNCH_GENERATION",
+            *_ISOLATED_DIRECTORIES,
+        }
+    ):
+        raise ValueError("--generation-env must be a non-reserved environment variable name")
     uv = shutil.which("uv")
     if uv is None:
         raise ValueError("uv must be installed and available on PATH")
@@ -261,20 +497,54 @@ def install(args: argparse.Namespace) -> dict:
         "timeout": args.timeout,
         "bin_dir": str(Path(args.bin_dir).expanduser().absolute()),
         "managed_updater": True,
+        "validate": args.validate or [],
+        "validation_timeout": args.validation_timeout,
+        "companions": list(dict.fromkeys(args.companion)),
+        "generation_env": args.generation_env,
     }
-    if args.name != "uv-launch":
-        config["requirements"].append("uv-launch>=0.2.1,<0.3")
+    if args.name != "uv-launch" or args.validate or args.companion or args.generation_env:
+        config["requirements"].append("uv-launch>=0.2.4,<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")
-    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):
+        previous = (
+            json.loads((root / "current/config.json").read_text())
+            if (root / "current").exists()
+            else {}
+        )
+        removed = set(previous.get("companions", [])) - set(config["companions"])
+        retired = dict(previous.get("retired_companions", {}))
+        for companion in removed:
+            if variable := previous.get("generation_env"):
+                retired[companion] = variable
+        for companion in config["companions"]:
+            retired.pop(companion, None)
+        if retired:
+            config["retired_companions"] = retired
+        for companion in [None, *config["companions"]]:
+            _launcher_destination(config, companion)
         result = refresh(root, config)
         destination = write_launcher(root, config)
+        for companion in config["companions"]:
+            write_launcher(root, config, command=companion)
+        for companion in retired:
+            path = Path(config["bin_dir"]) / companion
+            # Retiring a shim must leave user-owned replacements alone.
+            if not (path.exists() or path.is_symlink()) or _owned_launcher(path, config["name"]):
+                write_launcher(root, config, command=companion)
+        for companion in removed:
+            path = Path(previous["bin_dir"]) / companion
+            if _owned_launcher(path, config["name"]):
+                if companion in retired:
+                    # Also retire the original shim when --bin-dir changed.
+                    atomic_write(
+                        path,
+                        _launcher_content(root, config, sys.executable, command=companion),
+                        0o755,
+                    )
+                else:
+                    path.unlink()
     return {**result, "command": str(destination)}
@@ -352,6 +622,8 @@ def execute_installation(
     if metadata["identity"] != installation.identity:
         raise ValueError("installation identity does not match its generation")
     config = json.loads((generation / "config.json").read_text())
+    if variable := config.get("generation_env"):
+        os.environ[variable] = installation.generation
     selected = command or config["entrypoint"]
     if config.get("kind") == "source" and command is None:
         executable = generation / "command"
@@ -376,10 +648,31 @@ def main(argv: list[str] | None = None) -> int:
         "--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("--bin-dir", default=user_bin_path())
     installing.add_argument(
         "--timeout", type=float, default=600, help="seconds per update operation"
     )
+    installing.add_argument(
+        "--companion",
+        action="append",
+        default=[],
+        help="also expose this candidate command on PATH (repeatable)",
+    )
+    installing.add_argument(
+        "--generation-env",
+        help="environment variable used to export and pin the generation in every shim",
+    )
+    installing.add_argument(
+        "--validation-timeout",
+        type=float,
+        default=60,
+        help="seconds allowed for candidate validation (default: 60)",
+    )
+    installing.add_argument(
+        "--validate",
+        nargs=argparse.REMAINDER,
+        help="candidate command and fixed arguments to validate before activation; put last",
+    )
     source_installing = commands.add_parser(
         "install-source", help="install a toolfunc and adjacent files from a Git repository"
     )
@@ -389,7 +682,7 @@ def main(argv: list[str] | None = None) -> int:
     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("--bin-dir", default=user_bin_path())
     source_installing.add_argument("--timeout", type=float, default=600)
     source_installing.add_argument(
         "--prepare",
@@ -421,8 +714,10 @@ def main(argv: list[str] | None = None) -> int:
     previous_sigterm = signal.signal(signal.SIGTERM, _terminate)
     try:
         if args.command == "install":
-            if args.timeout <= 0:
-                raise ValueError("timeout must be positive")
+            if not math.isfinite(args.timeout) or args.timeout <= 0:
+                raise ValueError("timeout must be finite and positive")
+            if not math.isfinite(args.validation_timeout) or args.validation_timeout <= 0:
+                raise ValueError("validation timeout must be finite and positive")
             result = install(args)
         elif args.command == "install-source":
             from .source import install_source
@@ -459,12 +754,22 @@ def main(argv: list[str] | None = None) -> int:
             return 0
         else:
             root = tool_directory(args.name)
+            current = (root / "current").resolve()
+            if not current.exists() and not (root / "last-validation.json").exists():
+                raise ValueError(f"no installation found for {args.name!r}")
             result = {
-                "config": json.loads((root / "current/config.json").read_text()),
-                "active": json.loads((root / "current/installation.json").read_text()),
+                "config": json.loads((current / "config.json").read_text())
+                if current.exists()
+                else None,
+                "active": json.loads((current / "installation.json").read_text())
+                if current.exists()
+                else None,
                 "last_update": json.loads((root / "last-update.json").read_text())
                 if (root / "last-update.json").exists()
                 else None,
+                "last_validation": json.loads((root / "last-validation.json").read_text())
+                if (root / "last-validation.json").exists()
+                else None,
             }
         if not getattr(args, "background", False):
             sys.stdout.write(json.dumps(result, sort_keys=True) + "\n")

{uv_launch-0.2.2 → uv_launch-0.2.4}/src/uv_launch/dependencies.py RENAMED Viewed

@@ -329,8 +329,27 @@ def managed_target(source: Path) -> Path | None:
         raise ValueError("managed launcher root must be absolute")
     generation = (root / "current").resolve(strict=True)
     config = json.loads((generation / "config.json").read_text())
-    if source.read_text() != _launcher_content(root, config, manager_python):
+    content = source.read_text()
+    retired = config.get("retired_companions", {})
+    commands = [None, *config.get("companions", []), *retired]
+    matches = [
+        command
+        for command in commands
+        if content == _launcher_content(root, config, manager_python, command=command)
+    ]
+    if len(matches) != 1:
         raise ValueError("managed launcher content does not match its installation")
+    command = matches[0]
+    variable = retired[command] if command in retired else config.get("generation_env")
+    pin = os.environ.get(variable) if variable else None
+    if command in retired and not pin:
+        raise ValueError(
+            f"companion {command!r} is retired; an explicit {variable} pin is required"
+        )
+    if pin:
+        if not re.fullmatch(r"[a-f0-9]{32}", pin):
+            raise ValueError("invalid generation pin")
+        generation = (root / "generations" / pin).resolve(strict=True)
     if config.get("kind") == "source":
         from .source import source_command
@@ -340,7 +359,9 @@ def managed_target(source: Path) -> Path | None:
         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)
+    target = (
+        generation / "command" if command is None else generation / "venv/bin" / command
+    ).resolve(strict=True)
     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/PKG-INFO DELETED Viewed

@@ -1,103 +0,0 @@
-Metadata-Version: 2.3
-Name: uv-launch
-Version: 0.2.2
-Summary: Immediate Python command startup with atomic background updates through uv
-Requires-Dist: packaging>=24
-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/). 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
-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. 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
-A service can require the latest successfully resolved dependencies at startup:
-```sh
-uv-launch run --refresh my-command -- serve --port 8080
-```
-Unlike the ordinary background-updating shim, `run --refresh` waits for a successful update and fails without executing stale code when that update fails. It then replaces itself with the selected command. Arguments, environment, working directory and exit status are preserved. SIGTERM during refresh terminates and reaps the resolver/build process group; after execution the application receives signals directly. Old generations remain available for workers that outlive their launcher.
-Run a companion executable from the same installation with `uv-launch run --command python my-command -- -c 'print("probe")'`. Options to `run` precede the installation name. For several operations that must use exactly the same generation, capture once and pass the returned opaque `generation` value:
-```sh
-uv-launch select --refresh my-command
-uv-launch run --generation GENERATION --command python my-command -- -c 'print("probe")'
-uv-launch run --generation GENERATION my-command -- serve
-```
-The Python equivalents are `select_installation(name, refresh_dependencies=True)` and `execute_installation(installation, arguments, command=None)` from `uv_launch`. `execute_installation` uses `exec`, so successful execution does not return. Consumers should use these interfaces instead of reading installation symlinks or reconstructing generation paths.
-## Script runtimes and Python imports
-`uv_launch.dependencies` provides shared preparation for tools such as toolfuncs:
-- `prepare_environment(requirements, python=..., background=True)` returns a ready immutable virtual environment. Warm calls reuse a generation without foreground resolution; first use and changed requirements wait for preparation. It does not snapshot the caller's script.
-- `resolve_dependencies(requirements, python=..., constraints=(), background=True)` returns an immutable pinned requirements file. Resolutions are cached by requirements, interpreter/platform and constraints.
-- `install_dependencies(requirements)` adds missing packages to the **current interpreter's environment**. It reuses satisfying installed dependencies, constrains resolution to preserve existing distributions, checks the selected graph before installation, and raises `DependencyConflictError` if preservation is impossible. It never synchronizes the whole environment or replaces existing distributions. Background resolution refresh does not install into the active interpreter or reload modules.
-- `managed_target(path)` statically resolves a generated uv-launch command to its installed executable. It validates the shim against its recorded installation without executing shell code, importing the application, or requesting an update. This lets discovery tools inspect package metadata behind managed commands.
-The shared resolver accepts floating Git branches and records exact commit IDs in each cached resolution. No separate script registration or checked-in lockfile is required. A process already using an installed package retains that package; a new cached resolution is not a hot reload. Use a compatible environment when requirements conflict. Each installed source distribution is identified by its recorded origin or package version via `distribution_requirement(distribution)`.
-## 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.2.2/README.md DELETED Viewed

@@ -1,94 +0,0 @@
-# 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/). 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
-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. 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
-A service can require the latest successfully resolved dependencies at startup:
-```sh
-uv-launch run --refresh my-command -- serve --port 8080
-```
-Unlike the ordinary background-updating shim, `run --refresh` waits for a successful update and fails without executing stale code when that update fails. It then replaces itself with the selected command. Arguments, environment, working directory and exit status are preserved. SIGTERM during refresh terminates and reaps the resolver/build process group; after execution the application receives signals directly. Old generations remain available for workers that outlive their launcher.
-Run a companion executable from the same installation with `uv-launch run --command python my-command -- -c 'print("probe")'`. Options to `run` precede the installation name. For several operations that must use exactly the same generation, capture once and pass the returned opaque `generation` value:
-```sh
-uv-launch select --refresh my-command
-uv-launch run --generation GENERATION --command python my-command -- -c 'print("probe")'
-uv-launch run --generation GENERATION my-command -- serve
-```
-The Python equivalents are `select_installation(name, refresh_dependencies=True)` and `execute_installation(installation, arguments, command=None)` from `uv_launch`. `execute_installation` uses `exec`, so successful execution does not return. Consumers should use these interfaces instead of reading installation symlinks or reconstructing generation paths.
-## Script runtimes and Python imports
-`uv_launch.dependencies` provides shared preparation for tools such as toolfuncs:
-- `prepare_environment(requirements, python=..., background=True)` returns a ready immutable virtual environment. Warm calls reuse a generation without foreground resolution; first use and changed requirements wait for preparation. It does not snapshot the caller's script.
-- `resolve_dependencies(requirements, python=..., constraints=(), background=True)` returns an immutable pinned requirements file. Resolutions are cached by requirements, interpreter/platform and constraints.
-- `install_dependencies(requirements)` adds missing packages to the **current interpreter's environment**. It reuses satisfying installed dependencies, constrains resolution to preserve existing distributions, checks the selected graph before installation, and raises `DependencyConflictError` if preservation is impossible. It never synchronizes the whole environment or replaces existing distributions. Background resolution refresh does not install into the active interpreter or reload modules.
-- `managed_target(path)` statically resolves a generated uv-launch command to its installed executable. It validates the shim against its recorded installation without executing shell code, importing the application, or requesting an update. This lets discovery tools inspect package metadata behind managed commands.
-The shared resolver accepts floating Git branches and records exact commit IDs in each cached resolution. No separate script registration or checked-in lockfile is required. A process already using an installed package retains that package; a new cached resolution is not a hot reload. Use a compatible environment when requirements conflict. Each installed source distribution is identified by its recorded origin or package version via `distribution_requirement(distribution)`.
-## 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.2.2 → uv_launch-0.2.4}/src/uv_launch/__main__.py RENAMED Viewed

File without changes

{uv_launch-0.2.2 → uv_launch-0.2.4}/src/uv_launch/py.typed RENAMED Viewed

File without changes

{uv_launch-0.2.2 → uv_launch-0.2.4}/src/uv_launch/source.py RENAMED Viewed

File without changes

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

uv-launch 0.2.2tar.gz → 0.2.4tar.gz