From be654b5b418b01f95ecf4e0a3af1fb2bc212ccfd Mon Sep 17 00:00:00 2001 From: Thales Maciel Date: Mon, 9 Mar 2026 21:36:36 -0300 Subject: [PATCH] Clarify package install and run expectations --- README.md | 30 +++++++++++++++++++++++++++++- docs/first-run.md | 12 +++++++++++- docs/install.md | 16 +++++++++++++++- pyproject.toml | 1 + src/pyro_mcp/cli.py | 19 +++++++++++++++++-- tests/test_cli.py | 3 +++ 6 files changed, 76 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index bdfb26a..fdfd24e 100644 --- a/README.md +++ b/README.md @@ -12,6 +12,7 @@ It exposes the same runtime in three public forms: - Install: [docs/install.md](docs/install.md) - First run transcript: [docs/first-run.md](docs/first-run.md) +- PyPI package: [pypi.org/project/pyro-mcp](https://pypi.org/project/pyro-mcp/) - Host requirements: [docs/host-requirements.md](docs/host-requirements.md) - Integration targets: [docs/integrations.md](docs/integrations.md) - Public contract: [docs/public-contract.md](docs/public-contract.md) @@ -45,6 +46,19 @@ If you do not already have `uv`, install it first: python -m pip install uv ``` +Published package path: + +```bash +uvx --from pyro-mcp pyro doctor +uv tool install pyro-mcp +``` + +Source checkout path: + +```bash +uv run pyro doctor +``` + ## 5-Minute Evaluation Use the package directly without a manual install: @@ -85,6 +99,10 @@ debian:12-build [installed|not installed] Debian 12 environment with Git and com uvx --from pyro-mcp pyro env pull debian:12 ``` +The first pull downloads an OCI environment from public Docker Hub, requires outbound HTTPS +access to `registry-1.docker.io`, and needs local cache space for the guest image. +See [docs/host-requirements.md](docs/host-requirements.md) for the full host requirements. + ### 3. Run one command in a guest ```bash @@ -94,10 +112,14 @@ uvx --from pyro-mcp pyro run debian:12 -- git --version Expected success signals: ```bash -git version ... [run] environment=debian:12 execution_mode=guest_vsock exit_code=0 duration_ms=... +git version ... ``` +The guest command output and the `[run] ...` summary are written to different streams, so they +may appear in either order in terminals or capture tools. Use `--json` if you need a +deterministic structured result. + ### 4. Optional demos ```bash @@ -115,6 +137,12 @@ The public user-facing interface is `pyro` and `Pyro`. After the CLI validation - `from pyro_mcp import Pyro` for Python orchestration - `pyro mcp serve` for MCP clients +Command forms: + +- published package without install: `uvx --from pyro-mcp pyro ...` +- installed package: `pyro ...` +- source checkout: `uv run pyro ...` + `Makefile` targets are contributor conveniences for this repository and are not the primary product UX. ## Official Environments diff --git a/docs/first-run.md b/docs/first-run.md index e64d9cd..8cb8c11 100644 --- a/docs/first-run.md +++ b/docs/first-run.md @@ -2,6 +2,8 @@ This is the intended evaluator path for a first successful run on a supported host. Copy the commands as-is. Paths and timing values will differ on your machine. +If you are running from a source checkout instead of the published package, replace +`uvx --from pyro-mcp pyro` with `uv run pyro`. ## 1. Verify the host @@ -27,6 +29,10 @@ debian:12-build [installed|not installed] Debian 12 environment with Git and com ## 3. Pull the default environment +The first pull downloads an OCI environment from public Docker Hub, requires outbound HTTPS +access to `registry-1.docker.io`, and needs local cache space for the guest image. See +[host-requirements.md](host-requirements.md) for the full host requirements. + ```bash $ uvx --from pyro-mcp pyro env pull debian:12 Pulled: debian:12 @@ -46,10 +52,14 @@ OCI source: registry-1.docker.io/thalesmaciel/pyro-environment-debian-12:1.0.0 ```bash $ uvx --from pyro-mcp pyro run debian:12 -- git --version -git version ... [run] environment=debian:12 execution_mode=guest_vsock exit_code=0 duration_ms=... +git version ... ``` +The guest command output and the `[run] ...` summary are written to different streams, so they +may appear in either order in terminals or capture tools. Use `--json` if you need a +deterministic structured result. + ## 5. Optional next steps ```bash diff --git a/docs/install.md b/docs/install.md index e8ebc31..280d73f 100644 --- a/docs/install.md +++ b/docs/install.md @@ -27,6 +27,12 @@ If you do not already have `uv`, install it first: python -m pip install uv ``` +Use these command forms consistently: + +- published package without install: `uvx --from pyro-mcp pyro ...` +- installed package: `pyro ...` +- source checkout: `uv run pyro ...` + ## Fastest Evaluation Path Use the package directly without a manual install: @@ -71,6 +77,10 @@ debian:12-build [installed|not installed] Debian 12 environment with Git and com uvx --from pyro-mcp pyro env pull debian:12 ``` +The first pull downloads an OCI environment from public Docker Hub, requires outbound HTTPS +access to `registry-1.docker.io`, and needs local cache space for the guest image. See +[host-requirements.md](host-requirements.md) for the full host requirements. + ### 4. Run one command in a guest ```bash @@ -80,10 +90,14 @@ uvx --from pyro-mcp pyro run debian:12 -- git --version Expected success signals: ```bash -git version ... [run] environment=debian:12 execution_mode=guest_vsock exit_code=0 duration_ms=... +git version ... ``` +The guest command output and the `[run] ...` summary are written to different streams, so they +may appear in either order in terminals or capture tools. Use `--json` if you need a +deterministic structured result. + If guest execution is unavailable, the command fails unless you explicitly pass `--allow-host-compat`. diff --git a/pyproject.toml b/pyproject.toml index 2cf3199..7cde7e1 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -27,6 +27,7 @@ dependencies = [ Homepage = "https://git.thaloco.com/thaloco/pyro-mcp" Repository = "https://git.thaloco.com/thaloco/pyro-mcp" Issues = "https://git.thaloco.com/thaloco/pyro-mcp/issues" +PyPI = "https://pypi.org/project/pyro-mcp/" [project.scripts] pyro = "pyro_mcp.cli:main" diff --git a/src/pyro_mcp/cli.py b/src/pyro_mcp/cli.py index 676ff53..5edf3be 100644 --- a/src/pyro_mcp/cli.py +++ b/src/pyro_mcp/cli.py @@ -209,8 +209,19 @@ def _build_parser() -> argparse.ArgumentParser: pull_parser = env_subparsers.add_parser( "pull", help="Install an environment into the local cache.", - description="Download and install one official environment into the local cache.", - epilog="Example:\n pyro env pull debian:12", + description=( + "Download and install one official environment into the local cache from " + "the configured OCI registry." + ), + epilog=dedent( + """ + Example: + pyro env pull debian:12 + + The first pull downloads from public Docker Hub, requires outbound HTTPS, + and needs local cache space for the guest image. + """ + ), formatter_class=_HelpFormatter, ) pull_parser.add_argument( @@ -288,6 +299,10 @@ def _build_parser() -> argparse.ArgumentParser: Examples: pyro run debian:12 -- git --version pyro run debian:12 --network -- git ls-remote https://github.com/octocat/Hello-World.git + + The guest command output and the [run] summary are written to different + streams, so they may appear in either order. Use --json for a deterministic + structured result. """ ), formatter_class=_HelpFormatter, diff --git a/tests/test_cli.py b/tests/test_cli.py index 7891b51..2fd88e9 100644 --- a/tests/test_cli.py +++ b/tests/test_cli.py @@ -39,10 +39,13 @@ def test_cli_subcommand_help_includes_examples_and_guidance() -> None: assert "pyro run debian:12 -- git --version" in run_help assert "Opt into host-side compatibility execution" in run_help assert "Enable outbound guest networking" in run_help + assert "may appear in either order" in run_help + assert "Use --json for a deterministic" in run_help env_help = _subparser_choice(_subparser_choice(parser, "env"), "pull").format_help() assert "Environment name from `pyro env list`" in env_help assert "pyro env pull debian:12" in env_help + assert "downloads from public Docker Hub" in env_help doctor_help = _subparser_choice(parser, "doctor").format_help() assert "Check host prerequisites and embedded runtime health" in doctor_help