Quickly sandbox your AI agent.
Python
feat(cli): serve GitHub releases as PEP 503 simple index
Tyler Payne7e01b08061d6
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.ymlindex c9ee3cd..73c86f5 100644--- a/.github/workflows/docs.yml+++ b/.github/workflows/docs.yml@@ -7,6 +7,13 @@ on:- 'docs/**'- 'package.json'- 'package-lock.json'+ - 'scripts/ci/build_simple_index.py'+ - '.github/workflows/docs.yml'+ # The Release Wheels workflow tags + publishes per-package GitHub Releases.+ # Re-run docs after each successful release to refresh the simple/ index.+ workflow_run:+ workflows: [Release Wheels]+ types: [completed]workflow_dispatch: {}permissions:@@ -20,6 +27,8 @@ concurrency:jobs:build:+ # workflow_run fires on every Release Wheels completion; gate on success.+ if: ${{ github.event_name != 'workflow_run' || github.event.workflow_run.conclusion == 'success' }}runs-on: ubuntu-lateststeps:- uses: actions/checkout@v4@@ -33,6 +42,12 @@ jobs:- run: npm run docs:build+ - name: Build PEP 503 simple index from GitHub Releases+ env:+ GH_TOKEN: ${{ github.token }}+ GITHUB_REPOSITORY: ${{ github.repository }}+ run: python scripts/ci/build_simple_index.py docs/.vitepress/dist+- uses: actions/upload-pages-artifact@v3with:path: docs/.vitepress/distdiff --git a/packages/quicksand/quicksand/cli/install.py b/packages/quicksand/quicksand/cli/install.pyindex cecbe72..c5053d1 100644--- a/packages/quicksand/quicksand/cli/install.py+++ b/packages/quicksand/quicksand/cli/install.py@@ -1,18 +1,21 @@-"""Install optional quicksand extras from PyPI.+"""Install optional quicksand packages from the quicksand simple index.-Delegates version resolution and platform-wheel selection to ``pip``: a-package on PyPI under 100 MB ships as a fat wheel with images bundled in;-larger ones ship as a pure ``py3-none-any`` stub that pulls the matching-fat wheel from GitHub Releases on first install (via-:func:`quicksand_core._auto_install.auto_install_images`).+Delegates everything (version resolution, platform wheel selection,+transitive dependency resolution) to ``pip``. Every wheel attached to every+per-package GitHub release is exposed through a PEP 503 index at+``https://microsoft.github.io/quicksand/simple/``. PyPI is configured as an+extra index so transitive dependencies resolve normally.++Arguments use standard pip requirement syntax (PEP 508): ``quicksand-qemu``,+``quicksand-qemu==0.5.9``, ``quicksand-ubuntu>=0.4,<0.5``. Short aliases+(``qemu`` → ``quicksand-qemu``) are accepted in place of the project name.Programmatic API::from quicksand import install- install("qemu", "ubuntu") # install latest from PyPI- install("[email protected]") # pin a version- install("ubuntu", arch="amd64") # cross-arch image install+ install("qemu", "ubuntu") # latest+ install("ubuntu==0.4.0") # pin a version"""from __future__ import annotations@@ -21,10 +24,10 @@ import argparseimport platformimport subprocessimport sys-from importlib.metadata import entry_points-from pathlib import Path-# Short aliases → actual package names on PyPI+from packaging.requirements import Requirement++# Short aliases → actual project names on the simple index / PyPI.ALIASES: dict[str, list[str]] = {"qemu": ["quicksand-qemu"],"ubuntu": ["quicksand-ubuntu"],@@ -36,46 +39,62 @@ ALIASES: dict[str, list[str]] = {"dev": ["quicksand-image-tools", "quicksand-overlay-scaffold", "quicksand-base-scaffold"],}--# ── Helpers ───────────────────────────────────────────────────────────+# PEP 503 simple index served from the quicksand GitHub Pages site, listing+# every wheel attached to every per-package GitHub release. Falling back to+# PyPI keeps transitive dependencies (``pydantic``, ``anyio``, …) resolvable.+QUICKSAND_INDEX_URL = "https://microsoft.github.io/quicksand/simple/"+PYPI_INDEX_URL = "https://pypi.org/simple/"-def _parse_extra(raw: str) -> tuple[str, str | None]:- """Parse ``"name"`` or ``"name@version"`` into ``(name, version|None)``."""- if "@" in raw:- name, ver = raw.split("@", 1)- return name, ver- return raw, None+# ── Helpers ───────────────────────────────────────────────────────────-def _resolve_packages(name: str) -> list[str]:- """Resolve a name to a list of package names.+def _expand_requirement(raw: str) -> list[Requirement]:+ """Parse *raw* as a PEP 508 requirement, expanding aliases on the name.- Aliases (e.g. ``"ubuntu"``) expand to their mapped packages.- All other names are treated as literal package names.+ ``qemu==0.5.9`` → ``[Requirement("quicksand-qemu==0.5.9")]``.+ ``dev`` → three Requirements (one per package in the alias)."""- return ALIASES.get(name, [name])+ req = Requirement(raw)+ mapped = ALIASES.get(req.name, [req.name])+ if mapped == [req.name]:+ return [req]+ out: list[Requirement] = []+ for pkg in mapped:+ clone = Requirement(pkg)+ clone.specifier = req.specifier+ clone.extras = req.extras+ clone.marker = req.marker+ out.append(clone)+ return out+++def _collect(raw_requirements: list[str] | tuple[str, ...]) -> list[Requirement]:+ """Expand aliases and dedupe while preserving order."""+ seen: set[str] = set()+ out: list[Requirement] = []+ for raw in raw_requirements:+ for req in _expand_requirement(raw):+ key = str(req)+ if key not in seen:+ seen.add(key)+ out.append(req)+ return out# ── Public API ────────────────────────────────────────────────────────-def install(*extras: str, arch: str | None = None) -> None:- """Install quicksand extras from PyPI.-- Uses ``pip install`` so pip's resolver picks the version. Use- ``"name@version"`` to pin a specific version.+def install(*requirements: str) -> None:+ """Install quicksand packages from the GitHub-hosted simple index.- For image packages that ship as pure-Python stubs on PyPI (because the- fat wheel exceeds the 100 MB limit), images are fetched from the- matching GitHub release after pip install — pass ``arch`` to fetch- a different architecture's images for use with ``quicksand run --arch``.+ Uses ``pip install`` so pip's resolver picks versions. Pass standard+ pip requirement strings (``quicksand-qemu==0.5.9``, ``ubuntu>=0.4``)+ or the short aliases listed in :data:`ALIASES`.Args:- *extras: One or more extra/package names (e.g. ``"qemu"``, ``"ubuntu"``,- ``"[email protected]"``, ``"quicksand-agent"``).- arch: Target architecture for cross-arch image installs- (``"amd64"`` / ``"arm64"``).+ *requirements: PEP 508 requirements (e.g. ``"quicksand-qemu"``,+ ``"qemu==0.5.9"``, ``"ubuntu>=0.4,<0.5"``).Raises:RuntimeError: If pip install fails.@@ -85,24 +104,14 @@ def install(*extras: str, arch: str | None = None) -> None:from quicksand import installinstall("qemu", "ubuntu")- install("[email protected]")- install("ubuntu", arch="amd64") # cross-arch+ install("alpine==0.4.0")"""- if not extras:- raise ValueError("At least one extra name is required")-- packages: list[str] = []- versions: dict[str, str | None] = {}- for raw in extras:- name, ver = _parse_extra(raw)- for pkg in _resolve_packages(name):- if pkg not in packages:- packages.append(pkg)- versions[pkg] = ver-- rc = _install_packages(packages, versions, arch=arch)+ if not requirements:+ raise ValueError("At least one requirement is required")++ rc = _install_packages(_collect(requirements))if rc != 0:- raise RuntimeError(f"Failed to install packages: {packages}")+ raise RuntimeError("pip install failed")def register(subparsers: argparse._SubParsersAction) -> None:@@ -110,68 +119,44 @@ def register(subparsers: argparse._SubParsersAction) -> None:all_aliases = ", ".join(ALIASES.keys())parser = subparsers.add_parser("install",- help="Install packages from PyPI",+ help="Install packages from the quicksand simple index",)parser.add_argument(- "extras",+ "requirements",nargs="+",- metavar="NAME[@VERSION]",+ metavar="REQUIREMENT",help=(- f"Packages to install (use @version to pin, e.g. [email protected]). "- f"Aliases: {all_aliases}. "- "Other names are installed directly from PyPI."+ "Pip requirements (e.g. quicksand-qemu, qemu==0.5.9, ubuntu>=0.4). "+ f"Aliases: {all_aliases}."),)- parser.add_argument(- "--arch",- default=None,- help="Install images for a specific architecture (e.g. amd64, arm64). "- "Fetches cross-platform images from GitHub for use with quicksand run --arch.",- )def cmd(args: argparse.Namespace) -> int:- """Install packages from PyPI."""- packages: list[str] = []- versions: dict[str, str | None] = {}- for raw in args.extras:- name, ver = _parse_extra(raw)- for pkg in _resolve_packages(name):- if pkg not in packages:- packages.append(pkg)- versions[pkg] = ver-- return _install_packages(packages, versions, arch=args.arch)+ """Install packages from the quicksand simple index."""+ return _install_packages(_collect(args.requirements))# ── Implementation ────────────────────────────────────────────────────-def _install_packages(- packages: list[str],- versions: dict[str, str | None],- arch: str | None = None,-) -> int:- """Run ``pip install`` then fetch any missing images from GitHub."""- print(f"Installing: {', '.join(packages)}")+def _install_packages(requirements: list[Requirement]) -> int:+ """Run ``pip install`` against the quicksand simple index."""+ print(f"Installing: {', '.join(str(r) for r in requirements)}")print(f"Platform: {platform.system()} {platform.machine()}")- if arch:- print(f"Target image arch: {arch}")print()- rc = _run_pip_install(packages, versions)+ rc = _run_pip_install(requirements)if rc != 0:print("\nError: pip install failed.")return rc- _ensure_images(packages, arch=arch)-- print(f"\nInstalled {len(packages)} package(s)")+ print(f"\nInstalled {len(requirements)} package(s)")return 0-def _run_pip_install(packages: list[str], versions: dict[str, str | None]) -> int:- """Invoke ``pip install`` and let pip resolve versions from PyPI."""+def _run_pip_install(requirements: list[Requirement]) -> int:+ """Invoke ``pip install`` and let pip resolve versions from our indexes."""pip_args = [sys.executable,"-m",@@ -180,50 +165,12 @@ def _run_pip_install(packages: list[str], versions: dict[str, str | None]) -> in"--upgrade","--upgrade-strategy","only-if-needed",+ "--index-url",+ QUICKSAND_INDEX_URL,+ "--extra-index-url",+ PYPI_INDEX_URL,]- for pkg in packages:- ver = versions.get(pkg)- pip_args.append(f"{pkg}=={ver}" if ver else pkg)+ pip_args.extend(str(r) for r in requirements)print(f"Running: pip install {' '.join(pip_args[4:])}")return subprocess.run(pip_args).returncode---def _ensure_images(packages: list[str], arch: str | None = None) -> None:- """Fetch images from GitHub for any image-provider package in *packages*.-- Skipped automatically for packages whose fat wheel was installable from- PyPI (their ``manifest.json`` already exists). Forced when *arch* is set,- to overlay images for a different architecture.- """- requested = set(packages)- providers = _discover_image_providers(requested)- if not providers:- return-- from quicksand_core._auto_install import auto_install_images-- for pkg_name, images_dir in providers:- manifest = images_dir / "manifest.json"- if manifest.exists() and arch is None:- continue # fat wheel already on disk for the host- print(f"Fetching images for {pkg_name} (arch: {arch or 'host'})")- auto_install_images(pkg_name, images_dir, arch=arch)---def _discover_image_providers(requested: set[str]) -> list[tuple[str, Path]]:- """Return ``(pkg_name, images_dir)`` for every ``quicksand.images`` entry- point whose distribution is in *requested*."""- found: list[tuple[str, Path]] = []- for ep in entry_points(group="quicksand.images"):- dist = ep.dist- if dist is None or dist.name not in requested:- continue- try:- provider = ep.load()- except Exception:- continue- images_dir = getattr(provider, "images_dir", None)- if isinstance(images_dir, Path):- found.append((dist.name, images_dir))- return founddiff --git a/packages/quicksand/quicksand/cli/uninstall.py b/packages/quicksand/quicksand/cli/uninstall.pyindex add1c53..b02addf 100644--- a/packages/quicksand/quicksand/cli/uninstall.py+++ b/packages/quicksand/quicksand/cli/uninstall.py@@ -14,18 +14,27 @@ import argparseimport subprocessimport sys-from .install import ALIASES, _parse_extra, _resolve_packages+from .install import ALIASES-def uninstall(*extras: str) -> None:+def _resolve(names: list[str] | tuple[str, ...]) -> list[str]:+ """Expand aliases and dedupe."""+ packages: list[str] = []+ for raw in names:+ for pkg in ALIASES.get(raw, [raw]):+ if pkg not in packages:+ packages.append(pkg)+ return packages+++def uninstall(*names: str) -> None:"""Uninstall quicksand extras.Args:- *extras: One or more extra/package names (e.g. ``"qemu"``, ``"ubuntu"``,- ``"all"``).+ *names: One or more extra/package names (e.g. ``"qemu"``, ``"ubuntu"``).Raises:- ValueError: If no extras are provided.+ ValueError: If no names are provided.RuntimeError: If pip uninstall fails.Examples::@@ -33,18 +42,11 @@ def uninstall(*extras: str) -> None:from quicksand.cli.uninstall import uninstalluninstall("qemu", "ubuntu")- uninstall("all")"""- if not extras:- raise ValueError("At least one extra name is required")-- packages: list[str] = []- for raw in extras:- name, _ver = _parse_extra(raw)- for pkg in _resolve_packages(name):- if pkg not in packages:- packages.append(pkg)+ if not names:+ raise ValueError("At least one name is required")+ packages = _resolve(names)rc = _uninstall_packages(packages)if rc != 0:raise RuntimeError(f"Failed to uninstall packages: {packages}")@@ -58,7 +60,7 @@ def register(subparsers: argparse._SubParsersAction) -> None:help="Uninstall quicksand extras",)parser.add_argument(- "extras",+ "names",nargs="+",metavar="NAME",help=(f"Packages to uninstall. Aliases: {all_aliases}."),@@ -67,14 +69,7 @@ def register(subparsers: argparse._SubParsersAction) -> None:def cmd(args: argparse.Namespace) -> int:"""Uninstall quicksand extras."""- packages: list[str] = []- for raw in args.extras:- name, _ver = _parse_extra(raw)- for pkg in _resolve_packages(name):- if pkg not in packages:- packages.append(pkg)-- return _uninstall_packages(packages)+ return _uninstall_packages(_resolve(args.names))def _uninstall_packages(packages: list[str]) -> int:diff --git a/scripts/ci/build_simple_index.py b/scripts/ci/build_simple_index.pynew file mode 100644index 0000000..05f8bde--- /dev/null+++ b/scripts/ci/build_simple_index.py@@ -0,0 +1,153 @@+"""Generate a PEP 503 simple repository index from GitHub Releases.++Walks every release on the repo, groups wheels by their package name (parsed+from the per-package release tag, e.g. ``quicksand-qemu/v0.5.9``), and emits+static HTML pages that pip can consume::++ <root>/simple/index.html ← lists every package+ <root>/simple/<package>/index.html ← lists every wheel for the package++Run inside CI before the Pages artifact is uploaded so the index ships with+the docs site:++ python scripts/ci/build_simple_index.py docs/.vitepress/dist++Environment:+ GH_TOKEN: optional; raises GitHub API rate limits.+ GITHUB_REPOSITORY: ``owner/name`` (defaults to ``microsoft/quicksand``).+"""++from __future__ import annotations++import json+import os+import re+import sys+import urllib.request+from collections import defaultdict+from collections.abc import Iterator+from html import escape+from pathlib import Path++REPO = os.environ.get("GITHUB_REPOSITORY", "microsoft/quicksand")+API_ROOT = f"https://api.github.com/repos/{REPO}"++# Per-package release tags look like ``<pkg>/v<version>``. ``-base`` / ``-dev``+# suffixes denote internal markers, not user-installable releases.+_TAG_RE = re.compile(r"^(?P<pkg>[a-zA-Z0-9._-]+)/v(?P<version>.+?)(?:-base|-dev)?$")+++def _api(path: str) -> urllib.request.Request:+ req = urllib.request.Request(path)+ req.add_header("Accept", "application/vnd.github+json")+ token = os.environ.get("GH_TOKEN") or os.environ.get("GITHUB_TOKEN")+ if token:+ req.add_header("Authorization", f"Bearer {token}")+ return req+++def _paginate(path: str) -> Iterator[dict]:+ page = 1+ while True:+ url = f"{path}?per_page=100&page={page}"+ with urllib.request.urlopen(_api(url)) as resp:+ batch = json.load(resp)+ if not batch:+ return+ yield from batch+ if len(batch) < 100:+ return+ page += 1+++def _normalize(name: str) -> str:+ """PEP 503 name normalization: lowercase + runs of ``-_.`` collapsed to ``-``."""+ return re.sub(r"[-_.]+", "-", name).lower()+++def collect_releases() -> dict[str, list[dict]]:+ """Return ``{normalized_package_name: [wheel_asset, ...]}``.++ Each asset dict has ``filename`` and ``url`` keys.+ """+ by_pkg: dict[str, list[dict]] = defaultdict(list)+ for release in _paginate(f"{API_ROOT}/releases"):+ match = _TAG_RE.match(release["tag_name"])+ if not match:+ continue+ if release["tag_name"].endswith(("-base", "-dev")):+ continue+ pkg = _normalize(match.group("pkg"))+ for asset in release.get("assets", []):+ name = asset["name"]+ if not name.endswith(".whl"):+ continue+ by_pkg[pkg].append(+ {+ "filename": name,+ "url": asset["browser_download_url"],+ }+ )+ return by_pkg+++def render_package_page(package: str, assets: list[dict]) -> str:+ """Render the per-package PEP 503 page."""+ # Sort by filename for stable output.+ assets = sorted(assets, key=lambda a: a["filename"])+ lines = [+ "<!DOCTYPE html>",+ '<html><head><meta name="pypi:repository-version" content="1.0">',+ f"<title>Links for {escape(package)}</title>",+ "</head><body>",+ f"<h1>Links for {escape(package)}</h1>",+ ]+ for asset in assets:+ href = escape(asset["url"], quote=True)+ text = escape(asset["filename"])+ lines.append(f'<a href="{href}">{text}</a><br>')+ lines.append("</body></html>")+ return "\n".join(lines)+++def render_root_page(packages: list[str]) -> str:+ """Render ``simple/index.html`` listing every package."""+ packages = sorted(packages)+ lines = [+ "<!DOCTYPE html>",+ '<html><head><meta name="pypi:repository-version" content="1.0">',+ "<title>Simple Index</title>",+ "</head><body>",+ "<h1>Simple Index</h1>",+ ]+ for pkg in packages:+ lines.append(f'<a href="{escape(pkg, quote=True)}/">{escape(pkg)}</a><br>')+ lines.append("</body></html>")+ return "\n".join(lines)+++def main() -> int:+ if len(sys.argv) != 2:+ print(__doc__, file=sys.stderr)+ return 2+ out_root = Path(sys.argv[1]) / "simple"+ out_root.mkdir(parents=True, exist_ok=True)++ by_pkg = collect_releases()+ if not by_pkg:+ print("No wheel assets found across GitHub releases.", file=sys.stderr)+ return 1++ for pkg, assets in by_pkg.items():+ pkg_dir = out_root / pkg+ pkg_dir.mkdir(parents=True, exist_ok=True)+ (pkg_dir / "index.html").write_text(render_package_page(pkg, assets))+ print(f" {pkg}: {len(assets)} wheels")++ (out_root / "index.html").write_text(render_root_page(list(by_pkg)))+ print(f"\nGenerated index for {len(by_pkg)} package(s) at {out_root}")+ return 0+++if __name__ == "__main__":+ sys.exit(main())diff --git a/tests/unit/test_cli_install.py b/tests/unit/test_cli_install.pyindex fea9395..4091952 100644--- a/tests/unit/test_cli_install.py+++ b/tests/unit/test_cli_install.py@@ -3,48 +3,61 @@from __future__ import annotationsimport sys-from dataclasses import dataclass-from pathlib import Pathfrom unittest.mock import patchimport pytest-from quicksand.cli import install as install_mod+from packaging.requirements import Requirementfrom quicksand.cli.install import (- _ensure_images,+ _collect,+ _expand_requirement,_install_packages,- _parse_extra,- _resolve_packages,_run_pip_install,install,)-class TestParseExtra:- def test_bare_name(self):- assert _parse_extra("ubuntu") == ("ubuntu", None)+class TestExpandRequirement:+ def test_bare_alias(self):+ out = _expand_requirement("ubuntu")+ assert [str(r) for r in out] == ["quicksand-ubuntu"]- def test_pinned_version(self):- assert _parse_extra("[email protected]") == ("ubuntu", "0.4.0")+ def test_alias_with_specifier(self):+ out = _expand_requirement("qemu==0.5.9")+ assert [str(r) for r in out] == ["quicksand-qemu==0.5.9"]- def test_first_at_only(self):- # Versions can't contain "@", so split once.- assert _parse_extra("[email protected]@beta") == ("pkg", "1.0@beta")+ def test_range_specifier(self):+ out = _expand_requirement("ubuntu>=0.4,<0.5")+ assert len(out) == 1+ assert out[0].name == "quicksand-ubuntu"+ assert "0.4" in str(out[0].specifier) and "0.5" in str(out[0].specifier)--class TestResolvePackages:- def test_alias_expands(self):- assert _resolve_packages("ubuntu") == ["quicksand-ubuntu"]+ def test_literal_pypi_name_unchanged(self):+ out = _expand_requirement("quicksand-qemu==0.5.9")+ assert [str(r) for r in out] == ["quicksand-qemu==0.5.9"]def test_dev_alias_expands_to_multiple(self):- assert _resolve_packages("dev") == [+ out = _expand_requirement("dev")+ assert {r.name for r in out} == {"quicksand-image-tools","quicksand-overlay-scaffold","quicksand-base-scaffold",- ]+ }++ def test_dev_alias_propagates_specifier(self):+ out = _expand_requirement("dev>=0.3")+ for r in out:+ assert ">=0.3" in str(r.specifier)+- def test_unknown_is_passthrough(self):- # Treated as a literal PyPI name — pip will resolve or fail.- assert _resolve_packages("some-random-pkg") == ["some-random-pkg"]+class TestCollect:+ def test_dedupes_after_alias_expansion(self):+ # ``qemu`` and ``quicksand-qemu`` resolve to the same requirement.+ out = _collect(["qemu", "quicksand-qemu"])+ assert [str(r) for r in out] == ["quicksand-qemu"]++ def test_preserves_order(self):+ out = _collect(["ubuntu", "qemu"])+ assert [r.name for r in out] == ["quicksand-ubuntu", "quicksand-qemu"]class _DummyCompleted:@@ -60,114 +73,33 @@ class TestRunPipInstall:captured["argv"] = argvreturn _DummyCompleted(0)+ reqs = [Requirement("quicksand-qemu"), Requirement("quicksand-cua")]with patch("quicksand.cli.install.subprocess.run", side_effect=fake_run):- rc = _run_pip_install(["quicksand-qemu", "quicksand-cua"], {})+ rc = _run_pip_install(reqs)assert rc == 0- assert captured["argv"][:7] == [- sys.executable,- "-m",- "pip",- "install",- "--upgrade",- "--upgrade-strategy",- "only-if-needed",- ]- # Package args appear unpinned and in order.- assert captured["argv"][7:] == ["quicksand-qemu", "quicksand-cua"]-- def test_applies_version_pins(self):+ argv = captured["argv"]+ assert argv[:4] == [sys.executable, "-m", "pip", "install"]+ assert "--upgrade" in argv+ idx = argv.index("--index-url")+ assert argv[idx + 1] == "https://microsoft.github.io/quicksand/simple/"+ eidx = argv.index("--extra-index-url")+ assert argv[eidx + 1] == "https://pypi.org/simple/"+ assert argv[-2:] == ["quicksand-qemu", "quicksand-cua"]++ def test_forwards_specifiers(self):captured: dict = {}def fake_run(argv, *_args, **_kwargs):captured["argv"] = argvreturn _DummyCompleted(0)+ reqs = [Requirement("quicksand-qemu==0.5.9"), Requirement("quicksand-ubuntu>=0.4")]with patch("quicksand.cli.install.subprocess.run", side_effect=fake_run):- _run_pip_install(- ["quicksand-qemu", "quicksand-ubuntu"],- {"quicksand-qemu": "0.5.9", "quicksand-ubuntu": None},- )+ _run_pip_install(reqs)assert "quicksand-qemu==0.5.9" in captured["argv"]- assert "quicksand-ubuntu" in captured["argv"]- assert "quicksand-ubuntu==None" not in captured["argv"]---@dataclass-class _FakeDist:- name: str---class _FakeEntryPoint:- def __init__(self, dist_name: str, provider):- self.dist = _FakeDist(dist_name)- self._provider = provider-- def load(self):- return self._provider---class _FakeProvider:- def __init__(self, images_dir: Path) -> None:- self.images_dir = images_dir---class TestEnsureImages:- def test_skips_packages_not_in_request(self, tmp_path: Path):- images = tmp_path / "ubuntu-images"- images.mkdir()- eps = [_FakeEntryPoint("quicksand-ubuntu", _FakeProvider(images))]-- with (- patch("quicksand.cli.install.entry_points", return_value=eps),- patch("quicksand_core._auto_install.auto_install_images") as auto,- ):- _ensure_images(packages=["quicksand-qemu"], arch=None)-- auto.assert_not_called()-- def test_skips_when_manifest_present_and_no_arch(self, tmp_path: Path):- images = tmp_path / "ubuntu-images"- images.mkdir()- (images / "manifest.json").write_text("{}")- eps = [_FakeEntryPoint("quicksand-ubuntu", _FakeProvider(images))]-- with (- patch("quicksand.cli.install.entry_points", return_value=eps),- patch("quicksand_core._auto_install.auto_install_images") as auto,- ):- _ensure_images(packages=["quicksand-ubuntu"], arch=None)-- auto.assert_not_called()-- def test_fetches_when_manifest_missing(self, tmp_path: Path):- images = tmp_path / "ubuntu-images"- images.mkdir() # empty — pure-wheel install case- eps = [_FakeEntryPoint("quicksand-ubuntu", _FakeProvider(images))]-- with (- patch("quicksand.cli.install.entry_points", return_value=eps),- patch("quicksand_core._auto_install.auto_install_images") as auto,- ):- _ensure_images(packages=["quicksand-ubuntu"], arch=None)-- auto.assert_called_once_with("quicksand-ubuntu", images, arch=None)-- def test_fetches_for_cross_arch_even_with_manifest(self, tmp_path: Path):- # --arch forces a refetch so we can overlay images for a different arch.- images = tmp_path / "ubuntu-images"- images.mkdir()- (images / "manifest.json").write_text("{}")- eps = [_FakeEntryPoint("quicksand-ubuntu", _FakeProvider(images))]-- with (- patch("quicksand.cli.install.entry_points", return_value=eps),- patch("quicksand_core._auto_install.auto_install_images") as auto,- ):- _ensure_images(packages=["quicksand-ubuntu"], arch="amd64")-- auto.assert_called_once_with("quicksand-ubuntu", images, arch="amd64")+ assert "quicksand-ubuntu>=0.4" in captured["argv"]class TestInstall:@@ -177,36 +109,24 @@ class TestInstall:"quicksand.cli.install.subprocess.run",return_value=_DummyCompleted(1),),- pytest.raises(RuntimeError, match="Failed to install"),+ pytest.raises(RuntimeError, match="pip install failed"),):install("qemu")- def test_no_extras_raises(self):+ def test_no_requirements_raises(self):with pytest.raises(ValueError):install()- def test_install_packages_skips_image_fetch_on_pip_failure(self):- with (- patch(- "quicksand.cli.install.subprocess.run",- return_value=_DummyCompleted(2),- ),- patch.object(install_mod, "_ensure_images") as ensure,+ def test_install_packages_returns_pip_exit_code(self):+ with patch(+ "quicksand.cli.install.subprocess.run",+ return_value=_DummyCompleted(2),):- rc = _install_packages(["quicksand-ubuntu"], {}, arch=None)+ assert _install_packages([Requirement("quicksand-ubuntu")]) == 2- assert rc == 2- ensure.assert_not_called()-- def test_install_packages_calls_image_fetch_on_success(self):- with (- patch(- "quicksand.cli.install.subprocess.run",- return_value=_DummyCompleted(0),- ),- patch.object(install_mod, "_ensure_images") as ensure,+ def test_install_packages_succeeds(self):+ with patch(+ "quicksand.cli.install.subprocess.run",+ return_value=_DummyCompleted(0),):- rc = _install_packages(["quicksand-ubuntu"], {"quicksand-ubuntu": None}, arch="amd64")-- assert rc == 0- ensure.assert_called_once_with(["quicksand-ubuntu"], arch="amd64")+ assert _install_packages([Requirement("quicksand-ubuntu")]) == 0