toolfuncs 0.12.2__tar.gz → 0.12.4__tar.gz

{toolfuncs-0.12.2 → toolfuncs-0.12.4}/.github/workflows/release.yml

@@ -7,7 +7,7 @@ on:
 jobs:
   build:
     name: Build distributions
-    runs-on: [self-hosted, Linux, X64]
+    runs-on: ubuntu-latest
     permissions:
       contents: read
 
@@ -55,7 +55,7 @@ jobs:
   publish:
     name: Publish to PyPI
     needs: build
-    runs-on: [self-hosted, Linux, X64]
+    runs-on: ubuntu-latest
     environment:
       name: pypi
       url: https://pypi.org/project/toolfuncs/

{toolfuncs-0.12.2 → toolfuncs-0.12.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: toolfuncs
-Version: 0.12.2
+Version: 0.12.4
 Summary: Executable typed Python function tools invoked by path or discovered through PATH
 Project-URL: Repository, https://github.com/nimashoghi/toolfuncs
 Project-URL: Issues, https://github.com/nimashoghi/toolfuncs/issues
@@ -10,7 +10,7 @@ Requires-Dist: cyclopts<5,>=4.25.1
 Requires-Dist: packaging>=24
 Requires-Dist: pydantic-core<3,>=2
 Requires-Dist: pydantic<3,>=2
-Requires-Dist: uv-launch<0.3,>=0.2.1
+Requires-Dist: uv-launch<0.3,>=0.2.7
 Provides-Extra: hooks
 Requires-Dist: typed-agent-hooks; extra == 'hooks'
 Description-Content-Type: text/markdown
@@ -60,9 +60,13 @@ def describe(conversation: str) -> dict[str, str]:
     return {"conversation": conversation}
 ```
 
-Install with `uv-launch install agent-apps "agent-apps @ file:///absolute/path/to/project"` for managed launches, or with a normal package installer for an unmanaged command. The installer generates the console script; no separate handwritten executable, self-dependent PEP 723 script, custom backend, or registration command is needed. `agent-apps describe example` calls the same decorated function exposed as `toolfuncs.agent_apps.describe("example")`. Direct Python lookup returns the real `agent_apps.tools` module and native objects/exceptions.
+Install with `uv-launch install agent-apps "agent-apps @ file:///absolute/path/to/project"` for managed launches. Use uv-launch by default; it prepares and updates the command environment automatically. The installer generates the console script; no separate handwritten executable, self-dependent PEP 723 script, custom backend, or registration command is needed. `agent-apps describe example` calls the same decorated function exposed as `toolfuncs.agent_apps.describe("example")`. Direct Python lookup returns the real `agent_apps.tools` module and native objects/exceptions.
 
-Discovery reads the installed distribution's entry points, file ownership, and module docstring without importing or executing the target or preparing dependencies. It validates that the effective PATH launcher actually calls the declared `module:app`. Standard Python launchers, symlinks, installer-generated `/bin/sh` wrappers for long interpreter paths, and uv-launch managed commands are supported. The package must include inspectable Python source in its installation; arbitrary shell launchers and editable import-hook layouts are not inferred. The first docstring line is the static description.
+Discovery reads installed entry points, unique RECORD ownership, a strong launcher checksum, and the module docstring. It never imports a target, starts an interpreter, prepares dependencies, or uses the network. uv-launch records locate foreign command environments and capture one immutable generation. Packages installed in the caller's own interpreter use its metadata search paths. Generated launcher bodies are opaque: Python shebangs, long-path shell wrappers, and future installer templates follow the same ownership and checksum checks. Unmanaged foreign environments must be migrated with uv-launch; their interpreter locations are not inferred from executable text. Installed Python source is required; editable import-hook layouts are not inferred. The first docstring line is the static description.
+
+These checks detect inconsistent installations, not malicious package metadata. The package installer is trusted to generate the command declared by matching `console_scripts` and `toolfuncs` entry points. Discovery does not prove executable semantics or authenticate a publisher.
+
+Python consumers can call `toolfuncs.sdk.discover(path=...)` for the same static `Catalog` used by listing and agent hooks. Omit `path` to use PATH; a supplied path has the same first-executable precedence. Read `catalog.tools` and `catalog.invalid_tools` without executing command help.
 
 Direct Python loading installs the owning distribution into the caller's interpreter if needed, using its recorded exact Git origin, other direct origin, or published name/version. It then imports the actual module. This preserves native Python semantics rather than opening an RPC proxy into the tool environment. Use a suitable interpreter when tools have incompatible dependency requirements. `toolfuncs doctor /path/to/agent-apps` validates the installed module's registered commands and generated help. `import_path` retains its existing local-script contract and does not import package console wrappers.
 
@@ -277,7 +281,7 @@ Loading is intentional: the registered command graph and Cyclopts' effective par
 uvx --from "toolfuncs>=0.12" toolfuncs setup
 ```
 
-Setup installs uv-launch in a stable uv tool environment, prepares managed `toolfuncs` and `toolfuncs-agent-hook` commands, and writes small forwarding wrappers at `~/.local/bin/toolfuncs` and `~/.agents/hooks/toolfuncs/hook`. These wrappers no longer invoke uvx on each call. The destination must already be on PATH; setup is idempotent, refuses to overwrite unmanaged commands, and does not modify shell profiles.
+Setup bootstraps uv-launch through a transient `uv tool run` invocation, prepares managed `toolfuncs` and `toolfuncs-agent-hook` commands, and writes small forwarding wrappers at `~/.local/bin/toolfuncs` and `~/.agents/hooks/toolfuncs/hook`. These wrappers no longer invoke uvx on each call. The destination must already be on PATH; setup is idempotent, refuses to overwrite unmanaged commands, and does not modify shell profiles.
 
 Both shebang invocation and `toolfuncs SOURCE` delegate requirements to uv-launch before executing the source in an immutable environment. First use waits for installation. Warm calls reuse an existing environment and check for dependency updates in the background. Source edits run immediately; changed requirements or interpreter constraints select or prepare a matching environment before execution. Failed background updates leave the last working environment available. `toolfuncs doctor SOURCE` uses the same isolated preparation.
 

{toolfuncs-0.12.2 → toolfuncs-0.12.4}/README.md

@@ -43,9 +43,13 @@ def describe(conversation: str) -> dict[str, str]:
     return {"conversation": conversation}
 ```
 
-Install with `uv-launch install agent-apps "agent-apps @ file:///absolute/path/to/project"` for managed launches, or with a normal package installer for an unmanaged command. The installer generates the console script; no separate handwritten executable, self-dependent PEP 723 script, custom backend, or registration command is needed. `agent-apps describe example` calls the same decorated function exposed as `toolfuncs.agent_apps.describe("example")`. Direct Python lookup returns the real `agent_apps.tools` module and native objects/exceptions.
+Install with `uv-launch install agent-apps "agent-apps @ file:///absolute/path/to/project"` for managed launches. Use uv-launch by default; it prepares and updates the command environment automatically. The installer generates the console script; no separate handwritten executable, self-dependent PEP 723 script, custom backend, or registration command is needed. `agent-apps describe example` calls the same decorated function exposed as `toolfuncs.agent_apps.describe("example")`. Direct Python lookup returns the real `agent_apps.tools` module and native objects/exceptions.
 
-Discovery reads the installed distribution's entry points, file ownership, and module docstring without importing or executing the target or preparing dependencies. It validates that the effective PATH launcher actually calls the declared `module:app`. Standard Python launchers, symlinks, installer-generated `/bin/sh` wrappers for long interpreter paths, and uv-launch managed commands are supported. The package must include inspectable Python source in its installation; arbitrary shell launchers and editable import-hook layouts are not inferred. The first docstring line is the static description.
+Discovery reads installed entry points, unique RECORD ownership, a strong launcher checksum, and the module docstring. It never imports a target, starts an interpreter, prepares dependencies, or uses the network. uv-launch records locate foreign command environments and capture one immutable generation. Packages installed in the caller's own interpreter use its metadata search paths. Generated launcher bodies are opaque: Python shebangs, long-path shell wrappers, and future installer templates follow the same ownership and checksum checks. Unmanaged foreign environments must be migrated with uv-launch; their interpreter locations are not inferred from executable text. Installed Python source is required; editable import-hook layouts are not inferred. The first docstring line is the static description.
+
+These checks detect inconsistent installations, not malicious package metadata. The package installer is trusted to generate the command declared by matching `console_scripts` and `toolfuncs` entry points. Discovery does not prove executable semantics or authenticate a publisher.
+
+Python consumers can call `toolfuncs.sdk.discover(path=...)` for the same static `Catalog` used by listing and agent hooks. Omit `path` to use PATH; a supplied path has the same first-executable precedence. Read `catalog.tools` and `catalog.invalid_tools` without executing command help.
 
 Direct Python loading installs the owning distribution into the caller's interpreter if needed, using its recorded exact Git origin, other direct origin, or published name/version. It then imports the actual module. This preserves native Python semantics rather than opening an RPC proxy into the tool environment. Use a suitable interpreter when tools have incompatible dependency requirements. `toolfuncs doctor /path/to/agent-apps` validates the installed module's registered commands and generated help. `import_path` retains its existing local-script contract and does not import package console wrappers.
 
@@ -260,7 +264,7 @@ Loading is intentional: the registered command graph and Cyclopts' effective par
 uvx --from "toolfuncs>=0.12" toolfuncs setup
 ```
 
-Setup installs uv-launch in a stable uv tool environment, prepares managed `toolfuncs` and `toolfuncs-agent-hook` commands, and writes small forwarding wrappers at `~/.local/bin/toolfuncs` and `~/.agents/hooks/toolfuncs/hook`. These wrappers no longer invoke uvx on each call. The destination must already be on PATH; setup is idempotent, refuses to overwrite unmanaged commands, and does not modify shell profiles.
+Setup bootstraps uv-launch through a transient `uv tool run` invocation, prepares managed `toolfuncs` and `toolfuncs-agent-hook` commands, and writes small forwarding wrappers at `~/.local/bin/toolfuncs` and `~/.agents/hooks/toolfuncs/hook`. These wrappers no longer invoke uvx on each call. The destination must already be on PATH; setup is idempotent, refuses to overwrite unmanaged commands, and does not modify shell profiles.
 
 Both shebang invocation and `toolfuncs SOURCE` delegate requirements to uv-launch before executing the source in an immutable environment. First use waits for installation. Warm calls reuse an existing environment and check for dependency updates in the background. Source edits run immediately; changed requirements or interpreter constraints select or prepare a matching environment before execution. Failed background updates leave the last working environment available. `toolfuncs doctor SOURCE` uses the same isolated preparation.
 

{toolfuncs-0.12.2 → toolfuncs-0.12.4}/docs/contract.md

@@ -8,7 +8,9 @@ Toolfuncs projects one explicitly registered set of typed Python functions into
 
 An installed distribution opts a console script into discovery by declaring the same command name and `module:app` value in its `console_scripts` and `toolfuncs` entry-point groups. Authors normally express these as `[project.scripts]` and `[project.entry-points.toolfuncs]` in `pyproject.toml`. The module contains the same module-level `app` and decorated typed functions used by script tools. There is no hand-maintained launcher: normal installers generate it.
 
-The executable's kebab-case name determines the snake-case facade name, with the same reserved-name checks and PATH precedence as scripts. Distribution RECORD ownership and the actual generated launcher target must agree with the metadata. Discovery statically reads the installed module's first docstring line for its description. It does not import target packages, execute the interpreter, install dependencies, or query the network. Python-shebang launchers, symlinks, and installer-generated `/bin/sh` long-path wrappers and validated uv-launch shims are recognized; installed Python source is required. Arbitrary shell launchers and editable import-hook layouts are not interpreted.
+The public executable's kebab-case name determines its snake-case facade name, with the same reserved-name checks and PATH precedence as scripts. uv-launch's versioned installation records locate the actual executable and its metadata roots, capturing a single retained generation. The actual executable must have one distribution owner across all RECORD files, a matching strong checksum, and paired console-script and toolfuncs entry points. Discovery trusts the installer to implement those entry points. It does not parse generated Python or shell bodies or authenticate package metadata. Discovery statically reads the installed module's first docstring line and requires inspectable Python source.
+
+Metadata in the current interpreter is also supported, including additive native dependency preparation. Unmanaged foreign environments are not inferred from launcher text; install those commands through uv-launch. Discovery never imports target packages, starts a subprocess, installs dependencies, or queries the network. `toolfuncs.sdk.discover(path=None)` returns the same `Catalog` as CLI listing, with `tools` and `invalid_tools`.
 
 Python loading prepares the owning distribution in the caller's interpreter using its installed direct-origin metadata or name/version, then returns its real imported module. Git direct origins must identify a complete immutable commit. Returned functions, values, and exceptions are native Python objects; no remote proxy or subprocess API replaces them. `doctor` accepts the installed executable and validates the same registered interface. `import_path` remains a local-script importer.
 
@@ -90,7 +92,7 @@ Successful default CLI operations render one Python value through Rich on an int
 
 ## Setup and management
 
-`uvx --from "toolfuncs>=0.12" toolfuncs setup` bootstraps a stable uv-launch tool installation and prepares managed dispatcher and agent-hook commands. It installs forwarding wrappers in `~/.local/bin` or `--bin-dir`, and the agent hook location. The destination must already resolve from PATH. Setup is idempotent, refuses unmanaged commands, and never modifies shell profiles.
+`uvx --from "toolfuncs>=0.12" toolfuncs setup` bootstraps uv-launch through transient `uv tool run` and prepares managed dispatcher and agent-hook commands. It installs forwarding wrappers in `~/.local/bin` or `--bin-dir`, and the agent hook location. The destination must already resolve from PATH. Setup is idempotent, refuses unmanaged commands, and never modifies shell profiles.
 
 Setup does not discover, install, copy, link, register, synchronize, or remove tool sources. Adding and removing tools are ordinary filesystem operations in directories already on `PATH`.
 
@@ -98,7 +100,7 @@ The public management commands are `toolfuncs doctor SOURCE`, `toolfuncs list`,
 
 ## Compatibility
 
-Version 0.11 adds packaged tools through matching console-script and `toolfuncs` entry points. Normal `uv tool install` installations participate in PATH discovery, native Python loading, and `doctor` without a separate script. Existing standalone tools retain their interfaces.
+Version 0.11 adds packaged tools through matching console-script and `toolfuncs` entry points. In 0.12.3, use uv-launch for foreign command environments; unmanaged launcher inference from earlier releases has been removed. Existing standalone tools retain their interfaces.
 
 Version 0.10 adds destination-adaptive CLI presentation. Non-terminal output retains the strict-JSON behavior of earlier releases. Interactive output now uses Rich's normal rendering for returned Python values, and explicit Cyclopts output policies remain unchanged.
 
@@ -106,3 +108,5 @@ Version 0.8 adds explicit opt-in last-known dynamic descriptions through `[tool.
 
 
 Version 0.12 requires Python 3.11+ on macOS or Linux and delegates CLI environments and Python dependency preparation to uv-launch. Discovery recognizes uv-launch managed package commands through validated static launcher metadata. Existing installed distributions are preserved during Python imports; an incompatible dependency set is an explicit error.
+
+Version 0.12.3 uses uv-launch 0.2.6 discovery records and installed RECORD checksums instead of parsing launcher bodies. Updating or reinstalling through uv-launch writes records automatically, including for retained generations. Existing source tools retain their interfaces.

{toolfuncs-0.12.2 → toolfuncs-0.12.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "toolfuncs"
-version = "0.12.2"
+version = "0.12.4"
 description = "Executable typed Python function tools invoked by path or discovered through PATH"
 readme = "README.md"
 authors = [
@@ -10,7 +10,7 @@ requires-python = ">=3.11"
 dependencies = [
     "cyclopts>=4.25.1,<5",
     "packaging>=24",
-    "uv-launch>=0.2.1,<0.3",
+    "uv-launch>=0.2.7,<0.3",
     "pydantic>=2,<3",
     "pydantic-core>=2,<3",
 ]

toolfuncs-0.12.4/src/toolfuncs/_packages.py

@@ -0,0 +1,217 @@
+"""Static discovery of opted-in, normally installed Python console scripts."""
+
+from __future__ import annotations
+
+import ast
+import base64
+import hashlib
+import importlib
+import importlib.metadata
+import sys
+import sysconfig
+from dataclasses import dataclass
+from pathlib import Path
+from types import ModuleType
+
+from uv_launch.dependencies import distribution_requirement
+from uv_launch.records import metadata_paths
+
+from ._errors import InvalidToolError, ToolConflictError
+
+
+@dataclass(frozen=True, slots=True)
+class PackagedTool:
+    module: str
+    description: str
+    requirement: str
+    requires_python: str | None
+    distribution: str
+    version: str
+    source: Path
+
+
+@dataclass
+class _InstalledPackages:
+    owners: dict[Path, list[tuple[importlib.metadata.Distribution, importlib.metadata.PackagePath]]]
+    declarations: set[str]
+
+
+PackageIndex = dict[tuple[Path, ...], _InstalledPackages]
+
+
+def _index(paths: tuple[Path, ...], cache: PackageIndex) -> _InstalledPackages:
+    if paths not in cache:
+        owners = {}
+        distributions = list(importlib.metadata.distributions(path=[str(path) for path in paths]))
+        declarations = {
+            entry.name
+            for distribution in distributions
+            for entry in distribution.entry_points
+            if entry.group == "toolfuncs"
+        }
+        for distribution in distributions:
+            for file in distribution.files or ():
+                path = Path(str(distribution.locate_file(file)))
+                # A different leaf name can own an opted-in command only through
+                # a symlink. Avoid resolving every component of unrelated files.
+                if file.name not in declarations and not path.is_symlink():
+                    continue
+                path = path.resolve()
+                owners.setdefault(path, []).append((distribution, file))
+        cache[paths] = _InstalledPackages(owners, declarations)
+    return cache[paths]
+
+
+def _verify_file(source: Path, file: importlib.metadata.PackagePath) -> None:
+    if file.hash is None or file.hash.mode not in {"sha256", "sha384", "sha512"}:
+        raise InvalidToolError(f"{source}: installed launcher requires a strong RECORD checksum")
+    with source.open("rb") as stream:
+        digest = hashlib.file_digest(stream, file.hash.mode).digest()
+    actual = base64.urlsafe_b64encode(digest).rstrip(b"=").decode()
+    if actual != file.hash.value or (file.size is not None and source.stat().st_size != file.size):
+        raise InvalidToolError(f"{source}: installed launcher checksum does not match RECORD")
+
+
+def inspect_package(
+    source: Path, cli_name: str, cache: PackageIndex | None = None
+) -> PackagedTool | None:
+    try:
+        return _inspect_package(source, cli_name, cache)
+    except (OSError, ValueError, KeyError, TypeError) as error:
+        raise InvalidToolError(f"{source}: invalid installed tool metadata: {error}") from error
+
+
+def _inspect_package(
+    source: Path, cli_name: str, cache: PackageIndex | None
+) -> PackagedTool | None:
+    source = source.resolve(strict=True)
+    paths = metadata_paths(source)
+    installed_bin = (
+        paths is not None or source.parent == Path(sysconfig.get_path("scripts")).resolve()
+    )
+    if paths is None:
+        paths = tuple(
+            sorted({Path(value).resolve() for value in sys.path if value and Path(value).is_dir()})
+        )
+    index = _index(paths, {} if cache is None else cache)
+    owners = index.owners.get(source, [])
+    if not owners and installed_bin and source.name in index.declarations:
+        raise InvalidToolError(f"{source}: declared package tool has no RECORD ownership")
+
+    # Entry-point identity comes from the recorded executable, including when a
+    # public managed shim gives the installation a different name.
+    entry_name = source.name
+    if not any(
+        any(
+            entry.group == "toolfuncs" and entry.name == entry_name
+            for entry in distribution.entry_points
+        )
+        for distribution, _ in owners
+    ):
+        return None
+    if len(owners) != 1:
+        raise InvalidToolError(
+            f"{source}: toolfuncs package metadata does not uniquely own this launcher"
+        )
+    distribution, file = owners[0]
+    _verify_file(source, file)
+    entries = [entry for entry in distribution.entry_points if entry.name == entry_name]
+    tool = [entry for entry in entries if entry.group == "toolfuncs"]
+    console = [entry for entry in entries if entry.group == "console_scripts"]
+    if len(tool) != 1 or len(console) != 1 or tool[0].value != console[0].value:
+        raise InvalidToolError(f"{source}: toolfuncs and console_scripts entry points must match")
+    target = tool[0].value
+    module, _, attribute = target.partition(":")
+    if attribute != "app" or not all(part.isidentifier() for part in module.split(".")):
+        raise InvalidToolError(f"{source}: packaged tool entry point must name module:app")
+    sources = _module_sources(distribution, module)
+    if len(sources) != 1:
+        raise InvalidToolError(f"{source}: package must contain inspectable source for {module}")
+    try:
+        doc = ast.get_docstring(ast.parse(sources[0].read_text(encoding="utf-8")))
+    except (OSError, UnicodeError, SyntaxError) as error:
+        raise InvalidToolError(
+            f"{source}: cannot inspect package module source: {error}"
+        ) from error
+    if not doc or not doc.splitlines()[0].strip():
+        raise InvalidToolError(f"{source}: package module must have a descriptive docstring")
+    requires_python = None
+    if "Requires-Python" in distribution.metadata:
+        requires_python = distribution.metadata["Requires-Python"]
+    return PackagedTool(
+        module,
+        doc.splitlines()[0].strip(),
+        _requirement(distribution, source),
+        requires_python,
+        distribution.metadata["Name"],
+        distribution.version,
+        sources[0],
+    )
+
+
+def _module_sources(distribution: importlib.metadata.Distribution, module: str) -> list[Path]:
+    candidates = {module.replace(".", "/") + ".py", module.replace(".", "/") + "/__init__.py"}
+    return [
+        Path(str(distribution.locate_file(file)))
+        for file in distribution.files or ()
+        if str(file) in candidates
+    ]
+
+
+def _requirement(distribution: importlib.metadata.Distribution, source: Path) -> str:
+    try:
+        return distribution_requirement(distribution)
+    except ValueError as error:
+        raise InvalidToolError(f"{source}: {error}") from error
+
+
+def load_package(
+    package: PackagedTool, source: Path, *, dependencies_prepared: bool = False
+) -> ModuleType:
+    """Prepare the owning distribution, then return its real module in this process."""
+    from ._tools import _Metadata, _prepare_environment
+
+    metadata = _Metadata(
+        (package.requirement,),
+        package.requires_python,
+        package.description,
+        source.name,
+        source.name.replace("-", "_"),
+        False,
+    )
+    try:
+        installed = importlib.metadata.distribution(package.distribution)
+        prepared = (
+            installed.version == package.version
+            and _requirement(installed, source) == package.requirement
+            and len(_module_sources(installed, package.module)) == 1
+        )
+    except importlib.metadata.PackageNotFoundError:
+        prepared = False
+    if package.module in sys.modules and not prepared:
+        raise ToolConflictError(
+            f"{package.module} is already imported from a different installation"
+        )
+    _prepare_environment(metadata, source=source, install_dependencies=not dependencies_prepared)
+    installed = importlib.metadata.distribution(package.distribution)
+    if (
+        installed.version != package.version
+        or _requirement(installed, source) != package.requirement
+    ):
+        raise ToolConflictError(
+            f"{package.module} does not match the selected distribution version and origin"
+        )
+    module = importlib.import_module(package.module)
+    sources = _module_sources(installed, package.module)
+    if (
+        len(sources) != 1
+        or module.__file__ is None
+        or Path(module.__file__).resolve() != sources[0].resolve()
+    ):
+        raise ToolConflictError(
+            f"{package.module} does not resolve to the selected installed distribution"
+        )
+    from .sdk import _application
+
+    _application(module)
+    return module

{toolfuncs-0.12.2 → toolfuncs-0.12.4}/src/toolfuncs/_setup.py

@@ -73,17 +73,15 @@ def _prepare_launchers() -> tuple[Path, Path]:
     if uv is None:
         raise SetupError("uv must be installed and available on PATH")
     try:
-        subprocess.run([uv, "tool", "install", "--upgrade", "uv-launch>=0.2.1,<0.3"], check=True)
-        tools = subprocess.check_output([uv, "tool", "dir"], text=True).strip()
-        manager = Path(tools) / "uv-launch/bin/uv-launch"
+        manager = [uv, "tool", "run", "--from", "uv-launch>=0.2.6,<0.3", "uv-launch"]
         destination = state_root() / "bin"
         for name in ("toolfuncs", "toolfuncs-agent-hook"):
             subprocess.run(
                 [
-                    str(manager),
+                    *manager,
                     "install",
                     name,
-                    "toolfuncs[hooks]>=0.12.1,<0.13",
+                    "toolfuncs[hooks]>=0.12.3,<0.13",
                     "--bin-dir",
                     str(destination),
                 ],

{toolfuncs-0.12.2 → toolfuncs-0.12.4}/src/toolfuncs/_tools.py

@@ -107,8 +107,8 @@ def _discover(*, path: str | None = None) -> Catalog:
                 target = _managed_source(entry)
                 if _has_tool_shebang(target):
                     tools[name] = _inspect(target, cli_name=name)
-                elif (package := inspect_package(entry, name, packages)) is not None:
-                    tools[name] = _packaged_tool(entry, name, package)
+                elif (package := inspect_package(target, name, packages)) is not None:
+                    tools[name] = _packaged_tool(target, name, package)
             except InvalidToolError as exc:
                 error = str(exc)
                 prefix = f"{entry}: "
@@ -135,8 +135,8 @@ def _resolve(python_name: str, *, path: str | None = None) -> Tool:
             continue
         target = _managed_source(candidate)
         if not _has_tool_shebang(target):
-            if (package := inspect_package(candidate, cli_name)) is not None:
-                return _packaged_tool(candidate, cli_name, package)
+            if (package := inspect_package(target, cli_name)) is not None:
+                return _packaged_tool(target, cli_name, package)
             raise ToolNotFoundError(
                 f"command {cli_name!r} resolves to {candidate}, which is not a toolfuncs script"
             )

{toolfuncs-0.12.2 → toolfuncs-0.12.4}/src/toolfuncs/sdk.py

@@ -29,7 +29,7 @@ from rich.console import Console
 
 from ._descriptions import _publish_description
 from ._errors import ToolDefinitionError
-from ._tools import _python_name_for_cli_name
+from ._tools import Catalog, _discover, _python_name_for_cli_name
 
 _OUTPUT_ENVIRONMENT_VARIABLE = "TOOLFUNCS_OUTPUT"
 _OutputMode = Literal["terminal", "machine"]
@@ -37,6 +37,15 @@ _CONTROL_RESULT = object()
 _T = TypeVar("_T", bound=Callable[..., Any])
 
 
+def discover(*, path: str | None = None) -> Catalog:
+    """Inspect effective PATH tools without imports, subprocesses, or preparation.
+
+    The result separates valid tools from invalid opted-in commands. The first
+    executable always claims its name, even when it is not a supported tool.
+    """
+    return _discover(path=path)
+
+
 def json_result_action() -> ResultAction:
     """Return the standard strict-JSON Cyclopts result action."""
 
@@ -217,10 +226,12 @@ def _run(module: ModuleType, tokens: str | Iterable[str] | None = None) -> Any:
 __all__ = [
     "UNSET",
     "App",
+    "Catalog",
     "Group",
     "Parameter",
     "ResultAction",
     "Token",
+    "discover",
     "json_result_action",
     "publish_description",
     "to_jsonable_python",

{toolfuncs-0.12.2 → toolfuncs-0.12.4}/tests/test_packages.py

@@ -12,7 +12,7 @@ from importlib.metadata import distribution
 from pathlib import Path
 
 import pytest
-from uv_launch.dependencies import distribution_requirement
+from uv_launch.dependencies import distribution_requirement, managed_target
 
 from toolfuncs._errors import ToolNotFoundError
 from toolfuncs._tools import _discover, _resolve
@@ -86,13 +86,25 @@ allow-direct-references = true
     environment = {
         **os.environ,
         # Exercise installer-generated /bin/sh wrappers for long interpreter paths.
-        "UV_TOOL_DIR": str(
+        "UV_LAUNCH_HOME": str(
             root / ("long-environment-" + "x" * 100 if request.param == "long" else "tools")
         ),
-        "UV_TOOL_BIN_DIR": str(binary),
     }
     result = subprocess.run(
-        [uv, "tool", "install", "--python", sys.executable, str(project)],
+        [
+            sys.executable,
+            "-m",
+            "uv_launch",
+            "install",
+            "package-echo",
+            str(project),
+            "--python",
+            sys.executable,
+            "--bin-dir",
+            str(binary),
+            "--with",
+            distribution_requirement(distribution("uv-launch")),
+        ],
         env=environment,
         capture_output=True,
         text=True,
@@ -107,8 +119,7 @@ def test_real_uv_install_static_discovery_and_native_cli(installed_package, monk
     marker = root / "import-marker"
     monkeypatch.setenv("TOOLFUNCS_TEST_MARKER", str(marker))
     command = binary / "package-echo"
-    assert command.is_symlink()
-    assert command.read_text().startswith("#!/bin/sh\n") == (len(environment["UV_TOOL_DIR"]) > 100)
+    assert managed_target(command) is not None
     catalog = _discover(path=str(binary))
     assert catalog.invalid_tools == ()
     assert len(catalog.tools) == 1
@@ -182,49 +193,66 @@ def test_normal_path_shadowing_and_tampered_launcher(installed_package, tmp_path
     assert not _discover(path=path).tools
     with pytest.raises(ToolNotFoundError, match="not a toolfuncs"):
         _resolve("package_echo", path=path)
-    command = binary / "package-echo"
+    command = managed_target(binary / "package-echo")
+    assert command is not None
     original = command.read_text()
     try:
         command.write_text(original.replace("sys.exit(app())", "sys.exit(other())"))
         catalog = _discover(path=str(binary))
         assert not catalog.tools
-        assert "launcher target" in catalog.invalid_tools[0].error
+        assert "checksum" in catalog.invalid_tools[0].error
     finally:
         command.write_text(original)
 
 
 @pytest.mark.parametrize(
-    "normalization, valid",
+    "body",
     [
-        ("sys.argv[0].removesuffix('.exe')", True),
-        ("sys.argv[0].removesuffix(suffix())", False),
-        ("sys.argv[0].removesuffix('.exe', extra())", False),
+        "#!/bin/sh\nexec arbitrary-unexecuted-wrapper\n",
+        "#!/some/future/installer\nthis is not Python syntax\n",
     ],
 )
-def test_uv_removesuffix_launcher_discovery(installed_package, normalization, valid, monkeypatch):
+def test_recorded_wrapper_bytes_do_not_need_a_parser(installed_package, body, monkeypatch):
+    import base64
+    import csv
+    import hashlib
+    import io
+
     root, binary, _ = installed_package
-    marker = root / "removesuffix-import-marker"
+    command = managed_target(binary / "package-echo")
+    assert command is not None
+    tool = _discover(path=str(binary)).tools[0]
+    assert tool.package is not None
+    record = tool.package.source.parents[1] / "fixture_packaged_tool-0.0.1.dist-info/RECORD"
+    original, original_record = command.read_bytes(), record.read_text()
+    marker = root / "unexecuted-wrapper-marker"
     monkeypatch.setenv("TOOLFUNCS_TEST_MARKER", str(marker))
-    command = binary / "package-echo"
-    original = command.read_text()
-    prefix, _ = original.split("\nif __name__", 1)
     try:
-        command.write_text(
-            prefix
-            + "\nif __name__ == '__main__':\n"
-            + f"    sys.argv[0] = {normalization}\n"
-            + "    sys.exit(app())\n"
-        )
+        command.write_text(body)
+        rows = list(csv.reader(io.StringIO(original_record)))
+        for row in rows:
+            if row[0].endswith("bin/package-echo"):
+                digest = (
+                    base64.urlsafe_b64encode(hashlib.sha256(body.encode()).digest())
+                    .rstrip(b"=")
+                    .decode()
+                )
+                row[1:] = ["sha256=" + digest, str(len(body.encode()))]
+        output = io.StringIO()
+        csv.writer(output).writerows(rows)
+        record.write_text(output.getvalue())
+
+        def forbidden(*args, **kwargs):
+            raise AssertionError("discovery started a process")
+
+        monkeypatch.setattr(subprocess, "Popen", forbidden)
         catalog = _discover(path=str(binary))
-        assert not marker.exists(), "discovery executed package source"
-        if valid:
-            assert catalog.invalid_tools == ()
-            assert [tool.cli_name for tool in catalog.tools] == ["package-echo"]
-        else:
-            assert not catalog.tools
-            assert "launcher target" in catalog.invalid_tools[0].error
+        assert not catalog.invalid_tools
+        assert [tool.cli_name for tool in catalog.tools] == ["package-echo"]
+        assert not marker.exists()
     finally:
-        command.write_text(original)
+        command.write_bytes(original)
+        record.write_text(original_record)
 
 
 def test_package_metadata_must_opt_in_and_match(installed_package):
@@ -249,3 +277,114 @@ def test_package_metadata_must_opt_in_and_match(installed_package):
         assert "entry points must match" in catalog.invalid_tools[0].error
     finally:
         metadata.write_text(original)
+
+
+def test_current_interpreter_needs_no_managed_environment_record(installed_package):
+    _, binary, _ = installed_package
+    command = managed_target(binary / "package-echo")
+    assert command is not None
+    locator = command.parent / ".uv-launch.json"
+    original = locator.read_bytes()
+    try:
+        locator.unlink()
+        result = subprocess.run(
+            [
+                str(command.parent / "python"),
+                "-I",
+                "-c",
+                "from toolfuncs._tools import _discover; import sys; "
+                "c = _discover(path=sys.argv[1]); "
+                "assert not c.invalid_tools, c; "
+                "assert [t.cli_name for t in c.tools] == ['package-echo'], c",
+                str(command.parent),
+            ],
+            capture_output=True,
+            text=True,
+        )
+        assert result.returncode == 0, result.stderr
+    finally:
+        locator.write_bytes(original)
+
+
+@pytest.mark.parametrize("ownership", ["same-path", "leaf-symlink", "parent-symlink"])
+def test_unrelated_distribution_cannot_also_own_launcher(installed_package, ownership):
+    _, binary, _ = installed_package
+    package = _discover(path=str(binary)).tools[0].package
+    assert package is not None
+    metadata_root = package.source.parents[1]
+    other = metadata_root / "unrelated_owner-0.1.dist-info"
+    other.mkdir()
+    original_record = (metadata_root / "fixture_packaged_tool-0.0.1.dist-info/RECORD").read_text()
+    try:
+        (other / "METADATA").write_text(
+            "Metadata-Version: 2.1\nName: unrelated-owner\nVersion: 0.1\n"
+        )
+        row = next(line for line in original_record.splitlines() if "bin/package-echo," in line)
+        if ownership != "same-path":
+            target = managed_target(binary / "package-echo")
+            assert target is not None
+            alias = other / "alias"
+            alias.symlink_to(target if ownership == "leaf-symlink" else target.parent)
+            claim = alias if ownership == "leaf-symlink" else alias / target.name
+            row = f"{claim.relative_to(metadata_root)},,"
+        (other / "RECORD").write_text(row + "\n")
+        catalog = _discover(path=str(binary))
+        assert not catalog.tools
+        assert "uniquely own" in catalog.invalid_tools[0].error
+    finally:
+        shutil.rmtree(other)
+
+
+@pytest.mark.parametrize("damage", ["absent", "empty-hash"])
+def test_declared_package_requires_recorded_ownership_and_hash(installed_package, damage):
+    import csv
+    import io
+
+    _, binary, _ = installed_package
+    package = _discover(path=str(binary)).tools[0].package
+    assert package is not None
+    record = package.source.parents[1] / "fixture_packaged_tool-0.0.1.dist-info/RECORD"
+    original = record.read_text()
+    try:
+        if damage == "absent":
+            record.unlink()
+        else:
+            rows = list(csv.reader(io.StringIO(original)))
+            for row in rows:
+                if row[0].endswith("bin/package-echo"):
+                    row[1] = ""
+            output = io.StringIO()
+            csv.writer(output).writerows(rows)
+            record.write_text(output.getvalue())
+        catalog = _discover(path=str(binary))
+        assert not catalog.tools
+        assert "RECORD" in catalog.invalid_tools[0].error
+    finally:
+        record.write_text(original)
+
+
+def test_prepared_load_checks_selected_version_before_import(installed_package):
+    _, binary, _ = installed_package
+    command = managed_target(binary / "package-echo")
+    assert command is not None
+    code = """
+import sys
+from dataclasses import replace
+from pathlib import Path
+from toolfuncs._packages import inspect_package, load_package
+from toolfuncs._errors import ToolConflictError
+source = Path(sys.argv[1])
+package = inspect_package(source, 'package-echo')
+try:
+    load_package(replace(package, version='999'), source, dependencies_prepared=True)
+except ToolConflictError:
+    assert 'fixture_packaged_tool.operations' not in sys.modules
+else:
+    raise AssertionError('wrong version was imported')
+"""
+    result = subprocess.run(
+        [str(command.parent / "python"), "-I", "-c", code, str(command)],
+        capture_output=True,
+        text=True,
+    )
+    assert result.returncode == 0, result.stderr

{toolfuncs-0.12.2 → toolfuncs-0.12.4}/uv.lock

@@ -253,6 +253,15 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/63/34/ba1c580383c9eada3711951fef0795c80b829a078d72188184bcab9dd527/packaging-26.3-py3-none-any.whl", hash = "sha256:d7193f7c8e4e93f444fde0262bf90af30e16fa0ad0ad44cb553c87339b23cd1c", size = 129956, upload-time = "2026-08-04T18:15:27.159Z" },
 ]
 
+[[package]]
+name = "platformdirs"
+version = "4.13.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/80/a8/66d45abadff219e36e2a824181b8f6a67e7ed4572934d6252c71c29d5731/platformdirs-4.13.0.tar.gz", hash = "sha256:1aa0b0d3f224c1f07c295121e312a5a24a180d6ae5a8425ea1784b3e3863e9c0", size = 61094, upload-time = "2026-10-11T02:05:24.109Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/8d/15/1633010b26e88e872c93b67c0b6c5e174fb74cb6fb5c1472b4d51d4a8f22/platformdirs-4.13.0-py3-none-any.whl", hash = "sha256:3dbcf4cd708f21cf876c4eaa90e58412bc4f033d87143f41b1493ff77c25b7e1", size = 32724, upload-time = "2026-10-11T02:05:22.776Z" },
+]
+
 [[package]]
 name = "pluggy"
 version = "1.6.0"
@@ -534,7 +543,7 @@ wheels = [
 
 [[package]]
 name = "toolfuncs"
-version = "0.12.2"
+version = "0.12.4"
 source = { editable = "." }
 dependencies = [
     { name = "cyclopts" },
@@ -567,7 +576,7 @@ requires-dist = [
     { name = "pydantic", specifier = ">=2,<3" },
     { name = "pydantic-core", specifier = ">=2,<3" },
     { name = "typed-agent-hooks", marker = "extra == 'hooks'" },
-    { name = "uv-launch", specifier = ">=0.2.1,<0.3" },
+    { name = "uv-launch", specifier = ">=0.2.7,<0.3" },
 ]
 provides-extras = ["hooks"]
 
@@ -619,12 +628,13 @@ wheels = [
 
 [[package]]
 name = "uv-launch"
-version = "0.2.1"
+version = "0.2.7"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "packaging" },
+    { name = "platformdirs" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/1f/69/2dece5c99d309aaa4263bd8b0d01f29c6069ecec52bc44a267d2ad3e4f23/uv_launch-0.2.1.tar.gz", hash = "sha256:232259c49f3fa36fe65aaabe1898e71aaecda6bf849aa4878ceb256f0a6a7252", size = 14914, upload-time = "2026-10-02T23:52:26.887Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/53/d7/d37d4df64c61dd403729637f6a3797ddebfe6226851cb5285dfefec8aaaa/uv_launch-0.2.7.tar.gz", hash = "sha256:39fe10d1c06bde623ceed77e2ae128cf4d77b3602fce1c9f872aa39b809986ff", size = 25690, upload-time = "2026-10-13T16:21:33.966Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/f5/c1/fd02bf68cbf9064b837c5d488e7c109bcacb174841634ce5e3b59138cc73/uv_launch-0.2.1-py3-none-any.whl", hash = "sha256:cbc18ef98d347ee33aef283228ecafd43e6e2875694bd62ab67b5784b08f09e6", size = 17930, upload-time = "2026-10-02T23:52:25.659Z" },
+    { url = "https://files.pythonhosted.org/packages/6d/b1/e8fda697b8d8b01b7d34175a8a0138273df81ce27f7474e8ac5e34fd610f/uv_launch-0.2.7-py3-none-any.whl", hash = "sha256:d320f6ba61da8240e9c3ba58f955544b8b5d3d495ae6673e0423417d858babd4", size = 28126, upload-time = "2026-10-13T16:21:32.802Z" },
 ]

toolfuncs-0.12.2/src/toolfuncs/_packages.py

@@ -1,335 +0,0 @@
-"""Static discovery of opted-in, normally installed Python console scripts."""
-
-from __future__ import annotations
-
-import ast
-import importlib
-import importlib.metadata
-import re
-import shlex
-import shutil
-import sys
-from dataclasses import dataclass
-from pathlib import Path
-from types import ModuleType
-
-from uv_launch.dependencies import distribution_requirement, managed_target
-
-from ._errors import InvalidToolError, ToolConflictError
-
-
-@dataclass(frozen=True, slots=True)
-class PackagedTool:
-    module: str
-    description: str
-    requirement: str
-    requires_python: str | None
-    distribution: str
-    version: str
-    source: Path
-
-
-PackageIndex = dict[Path, dict[str, list[importlib.metadata.Distribution]]]
-
-
-def _interpreter(source: Path) -> tuple[Path, str] | None:
-    try:
-        with source.open("rb") as stream:
-            first = stream.readline(4096)
-            if not first.startswith(b"#!"):
-                return None
-            if b"python" not in first and first.rstrip() != b"#!/bin/sh":
-                return None
-            prefix = first
-            if first.rstrip() == b"#!/bin/sh":
-                second = stream.readline(4096)
-                if not second.startswith(b"'''exec' "):
-                    return None
-                prefix += second
-            raw = prefix + stream.read(65537 - len(prefix))
-        if len(raw) > 65536:
-            return None
-        text = raw.decode("utf-8")
-    except (OSError, UnicodeError):
-        return None
-    lines = text.splitlines()
-    if not lines or not lines[0].startswith("#!"):
-        return None
-    try:
-        words = shlex.split(lines[0][2:])
-        if words == ["/bin/sh"]:
-            if len(lines) < 3 or lines[2] != "' '''":
-                return None
-            match = re.fullmatch(r"'''exec' (.+) \"\$0\" \"\$@\"", lines[1])
-            if match is None:
-                return None
-            words = shlex.split(match[1])
-        if len(words) == 2 and words[0] == "/usr/bin/env":
-            resolved = shutil.which(words[1])
-            if resolved is None:
-                return None
-            words = [resolved]
-        if len(words) != 1 or not Path(words[0]).name.startswith("python"):
-            return None
-        interpreter = Path(words[0])
-        if not interpreter.is_absolute() or not interpreter.is_file():
-            return None
-        # Do not resolve this symlink: its containing venv owns the script.
-        return interpreter, text
-    except ValueError:
-        return None
-
-
-def _index(
-    interpreter: Path, cache: PackageIndex
-) -> dict[str, list[importlib.metadata.Distribution]]:
-    prefix = interpreter.parent.parent
-    if prefix in cache:
-        return cache[prefix]
-    paths = list(prefix.glob("lib/python*/site-packages"))
-    paths.extend(prefix.glob("Lib/site-packages"))
-    if prefix == Path(sys.prefix):
-        paths.extend(Path(value) for value in sys.path if value)
-    index: dict[str, list[importlib.metadata.Distribution]] = {}
-    for distribution in importlib.metadata.distributions(
-        path=[str(path) for path in {path.resolve() for path in paths}]
-    ):
-        for entry in distribution.entry_points:
-            if entry.group == "toolfuncs":
-                index.setdefault(entry.name, []).append(distribution)
-    cache[prefix] = index
-    return index
-
-
-def _launcher_target(text: str) -> str | None:
-    """Recognize installer wrappers without evaluating them or their imports."""
-    try:
-        tree = ast.parse(text)
-    except SyntaxError:
-        return None
-    imported: dict[str, str] = {}
-    guards: list[ast.If] = []
-    for node in tree.body:
-        if (
-            isinstance(node, ast.Expr)
-            and isinstance(node.value, ast.Constant)
-            and isinstance(node.value.value, str)
-        ):
-            continue
-        if isinstance(node, ast.Import) and all(
-            value.name in {"sys", "re"} and value.asname is None for value in node.names
-        ):
-            continue
-        if isinstance(node, ast.ImportFrom) and node.module and node.level == 0:
-            for name in node.names:
-                if (name.asname or name.name) in {"sys", "re"}:
-                    return None
-                imported[name.asname or name.name] = f"{node.module}:{name.name}"
-            continue
-        if isinstance(node, ast.If) and ast.dump(node.test) == ast.dump(
-            ast.parse("__name__ == '__main__'", mode="eval").body
-        ):
-            guards.append(node)
-            continue
-        return None
-    if len(imported) != 1 or len(guards) != 1 or guards[0].orelse:
-        return None
-    body = guards[0].body
-    if not body or not isinstance(body[-1], ast.Expr):
-        return None
-    exit_call = body[-1].value
-    if (
-        not isinstance(exit_call, ast.Call)
-        or ast.unparse(exit_call.func) != "sys.exit"
-        or len(exit_call.args) != 1
-        or exit_call.keywords
-    ):
-        return None
-    invocation = exit_call.args[0]
-    if (
-        not isinstance(invocation, ast.Call)
-        or invocation.args
-        or invocation.keywords
-        or not isinstance(invocation.func, ast.Name)
-    ):
-        return None
-    # uv and pip/distlib normalize argv[0] before the single target call.
-    if not all(_argv_normalization(statement) for statement in body[:-1]):
-        return None
-    return imported.get(invocation.func.id)
-
-
-def _argv_normalization(node: ast.stmt) -> bool:
-    if isinstance(node, ast.If):
-        test = node.test
-        return (
-            isinstance(test, ast.Call)
-            and ast.unparse(test.func) == "sys.argv[0].endswith"
-            and len(test.args) == 1
-            and isinstance(test.args[0], ast.Constant)
-            and isinstance(test.args[0].value, str)
-            and not test.keywords
-            and all(_argv_normalization(child) for child in [*node.body, *node.orelse])
-        )
-    if (
-        not isinstance(node, ast.Assign)
-        or len(node.targets) != 1
-        or ast.unparse(node.targets[0]) != "sys.argv[0]"
-    ):
-        return False
-    value = node.value
-    if isinstance(value, ast.Call):
-        if ast.unparse(value.func) == "sys.argv[0].removesuffix":
-            return (
-                len(value.args) == 1
-                and isinstance(value.args[0], ast.Constant)
-                and isinstance(value.args[0].value, str)
-                and not value.keywords
-            )
-        return (
-            ast.unparse(value.func) == "re.sub"
-            and len(value.args) == 3
-            and not value.keywords
-            and all(
-                isinstance(arg, ast.Constant) and isinstance(arg.value, str)
-                for arg in value.args[:2]
-            )
-            and ast.unparse(value.args[2]) == "sys.argv[0]"
-        )
-    return (
-        isinstance(value, ast.Subscript)
-        and ast.unparse(value.value) == "sys.argv[0]"
-        and all(
-            isinstance(child, (ast.Slice, ast.Constant, ast.UnaryOp, ast.USub, ast.Load))
-            for child in ast.walk(value.slice)
-        )
-    )
-
-
-def inspect_package(
-    source: Path, cli_name: str, cache: PackageIndex | None = None
-) -> PackagedTool | None:
-    try:
-        return _inspect_package(source, cli_name, cache)
-    except (OSError, ValueError, KeyError, TypeError) as error:
-        raise InvalidToolError(f"{source}: invalid installed tool metadata: {error}") from error
-
-
-def _inspect_package(
-    source: Path, cli_name: str, cache: PackageIndex | None
-) -> PackagedTool | None:
-    source = managed_target(source) or source
-    launcher = _interpreter(source)
-    if launcher is None:
-        return None
-    interpreter, text = launcher
-    distributions = _index(interpreter, {} if cache is None else cache).get(cli_name, [])
-    if not distributions:
-        return None
-    matches = []
-    for distribution in distributions:
-        files = distribution.files or ()
-        if any(
-            Path(str(distribution.locate_file(file))).resolve() == source.resolve()
-            for file in files
-        ):
-            matches.append(distribution)
-    if len(matches) != 1:
-        raise InvalidToolError(
-            f"{source}: toolfuncs package metadata does not uniquely own this launcher"
-        )
-    distribution = matches[0]
-    entries = [entry for entry in distribution.entry_points if entry.name == cli_name]
-    tool = [entry for entry in entries if entry.group == "toolfuncs"]
-    console = [entry for entry in entries if entry.group == "console_scripts"]
-    if len(tool) != 1 or len(console) != 1 or tool[0].value != console[0].value:
-        raise InvalidToolError(f"{source}: toolfuncs and console_scripts entry points must match")
-    target = tool[0].value
-    if _launcher_target(text) != target:
-        raise InvalidToolError(
-            f"{source}: launcher target does not match its toolfuncs entry point"
-        )
-    module, _, attribute = target.partition(":")
-    if attribute != "app" or not all(part.isidentifier() for part in module.split(".")):
-        raise InvalidToolError(f"{source}: packaged tool entry point must name module:app")
-    sources = _module_sources(distribution, module)
-    if len(sources) != 1:
-        raise InvalidToolError(f"{source}: package must contain inspectable source for {module}")
-    try:
-        doc = ast.get_docstring(ast.parse(sources[0].read_text(encoding="utf-8")))
-    except (OSError, UnicodeError, SyntaxError) as error:
-        raise InvalidToolError(
-            f"{source}: cannot inspect package module source: {error}"
-        ) from error
-    if not doc or not doc.splitlines()[0].strip():
-        raise InvalidToolError(f"{source}: package module must have a descriptive docstring")
-    return PackagedTool(
-        module,
-        doc.splitlines()[0].strip(),
-        _requirement(distribution, source),
-        distribution.metadata.get("Requires-Python"),
-        distribution.metadata["Name"],
-        distribution.version,
-        sources[0],
-    )
-
-
-def _module_sources(distribution: importlib.metadata.Distribution, module: str) -> list[Path]:
-    candidates = {module.replace(".", "/") + ".py", module.replace(".", "/") + "/__init__.py"}
-    return [
-        Path(str(distribution.locate_file(file)))
-        for file in distribution.files or ()
-        if str(file) in candidates
-    ]
-
-
-def _requirement(distribution: importlib.metadata.Distribution, source: Path) -> str:
-    try:
-        return distribution_requirement(distribution)
-    except ValueError as error:
-        raise InvalidToolError(f"{source}: {error}") from error
-
-
-def load_package(
-    package: PackagedTool, source: Path, *, dependencies_prepared: bool = False
-) -> ModuleType:
-    """Prepare the owning distribution, then return its real module in this process."""
-    from ._tools import _Metadata, _prepare_environment
-
-    metadata = _Metadata(
-        (package.requirement,),
-        package.requires_python,
-        package.description,
-        source.name,
-        source.name.replace("-", "_"),
-        False,
-    )
-    try:
-        installed = importlib.metadata.distribution(package.distribution)
-        prepared = (
-            installed.version == package.version
-            and _requirement(installed, source) == package.requirement
-            and len(_module_sources(installed, package.module)) == 1
-        )
-    except importlib.metadata.PackageNotFoundError:
-        prepared = False
-    if package.module in sys.modules and not prepared:
-        raise ToolConflictError(
-            f"{package.module} is already imported from a different installation"
-        )
-    _prepare_environment(metadata, source=source, install_dependencies=not dependencies_prepared)
-    module = importlib.import_module(package.module)
-    installed = importlib.metadata.distribution(package.distribution)
-    sources = _module_sources(installed, package.module)
-    if (
-        len(sources) != 1
-        or module.__file__ is None
-        or Path(module.__file__).resolve() != sources[0].resolve()
-    ):
-        raise ToolConflictError(
-            f"{package.module} does not resolve to the selected installed distribution"
-        )
-    from .sdk import _application
-
-    _application(module)
-    return module