External/pmg
1
0
Fork 0
mirror of https://github.com/safedep/pmg.git synced 2026-08-03 07:24:09 +02:00
Code Issues Packages Projects Releases Wiki Activity

feat: add uvx (uv tool run) package executor (#357)

Browse Source 
* feat(uvx): add uvx (uv tool run) package executor

Adds support for `uvx`, implemented as a PyPI Executor alongside pipx.
uvx is an alias for `uv tool run`: it installs a tool into an ephemeral
environment and runs it, so it has no install/list subcommand and the
first positional argument (or --from) is the package to audit.

Parsing highlights:
- --from overrides the positional command as the package to audit
- --with packages are audited as additional environment dependencies
- name@version shorthand (ruff@0.3.0, ruff@latest) is normalized
- flag parsing stops at the tool name so the tool's own flags are not
  misread as uvx options; uvx's value/boolean flags are registered so
  none greedily consume the package positional
- VCS/URL/local-path specs are skipped for registry auditing

Wires up command registration, analytics, shell alias/shim, cloud audit
mapping, a dedicated `uvx` sandbox profile (UV_*/PIP_* env, uv cache and
tool dirs), config policy, docs, unit tests and an E2E workflow step.

Closes #326

https://claude.ai/code/session_011hyLxq7oWJX5Dp4tCEfG19

* chore(uvx): align docs and base profile with uvx support

Incorporates the low-risk, non-parser improvements from the community
PR #345 (author non-responsive) into our implementation:

- list uvx (and the previously-missing pipx) as PyPI managers in the
  pypi-restrictive base profile package_managers and its README, so the
  base profile applies directly when selected via --sandbox-profile
- document uvx in docs/github-action.md and docs/proxy-mode.md
- add version / IsExplicitVersion assertions to the uvx parser tests

Our pflag-based parser is kept as-is: unlike #345 it audits --with
packages and handles all uvx short flags (e.g. -w), both of which the
community PR misses.

* fix(uvx): skip interpreter requests; use require in tests

Addresses review feedback on PR #357:

- uvx interpreter requests (`uvx python`, `uvx python@3.12`, `uvx pypy`,
  ...) launch an isolated interpreter rather than installing a PyPI tool.
  Treating the positional as a package made the guard flow resolve/analyze
  pkg:pypi/python (and python==3.12), which could wrongly block or fail a
  valid invocation. Skip these for the positional; --with packages on the
  same command are still audited.
- Use require.NoError / require.Len for fatal assertions in the uvx tests,
  matching the repo's testing convention, so a failure stops the subtest
  before a nil dereference instead of panicking.

* docs(uvx): document fail-open and --with-requirements trade-offs

Record the two deliberate parsing decisions raised in review as in-code
trade-off comments (no behavior change):

- unknown flags are tolerated (fail open), consistent with the other
  executors; the residual gap only affects non-proxy guard mode since the
  default proxy flow intercepts every registry download.
- --with-requirements / --with-editable values are consumed but not
  expanded into audit targets; expanding them needs manifest-extractor and
  guard changes, tracked as follow-up. Proxy mode still covers them.

* docs(uvx): drop --with-requirements limitation note

Per maintainer review: guard mode is being deprecated and auditing the
contents of an existing requirements file is a scanner's responsibility,
not PMG's. Remove the "known limitation / follow-up" note; the flags stay
registered only so their values are not mistaken for the tool positional.

---------

Co-authored-by: Claude <noreply@anthropic.com>
This commit is contained in:
Abhisek Datta
2026-07-02 18:49:31 +05:30
committed by GitHub
co-authored by Claude
parent 0fb6faa951
commit 648adcbda4
21 changed files with 717 additions and 7 deletions
Download Patch File Download Diff File Expand all files Collapse all files
packagemanager/pypi_uvx_executor_test.go
+329
View File
@@ -0,0 +1,329 @@
package packagemanager
import (
"strings"
"testing"
"github.com/stretchr/testify/assert"
"github.com/stretchr/testify/require"
)
func TestUvxExecutorParseCommand(t *testing.T) {
pm, err := NewPypiPackageExecutor(DefaultUvxPackageExecutorConfig())
require.NoError(t, err)
cases := []struct {
name string
args []string
expectedTargets int
expectedPackages []string
}{
{
name: "simple tool",
args: []string{"ruff"},
expectedTargets: 1,
expectedPackages: []string{"ruff"},
},
{
name: "tool with its own args is not a package",
args: []string{"ruff", "check", "."},
expectedTargets: 1,
expectedPackages: []string{"ruff"},
},
{
name: "tool with its own flags is not parsed as uvx flags",
args: []string{"ruff", "--fix", "--no-cache"},
expectedTargets: 1,
expectedPackages: []string{"ruff"},
},
{
name: "version pin via @ syntax",
args: []string{"ruff@0.3.0"},
expectedTargets: 1,
expectedPackages: []string{"ruff"},
},
{
name: "version @latest drops constraint",
args: []string{"ruff@latest"},
expectedTargets: 1,
expectedPackages: []string{"ruff"},
},
{
name: "version pin via == specifier",
args: []string{"ruff==0.3.0"},
expectedTargets: 1,
expectedPackages: []string{"ruff"},
},
{
name: "extras with version",
args: []string{"mypy[faster-cache]@1.0.0"},
expectedTargets: 1,
expectedPackages: []string{"mypy"},
},
{
name: "--from overrides positional command",
args: []string{"--from", "httpie", "http"},
expectedTargets: 1,
expectedPackages: []string{"httpie"},
},
{
name: "--from with version and positional command",
args: []string{"--from", "ruff==0.3.0", "ruff", "--check", "."},
expectedTargets: 1,
expectedPackages: []string{"ruff"},
},
{
name: "--from with @ version",
args: []string{"--from", "ruff@0.3.0", "ruff"},
expectedTargets: 1,
expectedPackages: []string{"ruff"},
},
{
name: "--with adds extra packages",
args: []string{"--with", "rich", "mkdocs"},
expectedTargets: 2,
expectedPackages: []string{"mkdocs", "rich"},
},
{
name: "repeated --with collects all",
args: []string{"--with", "rich", "--with", "pygments", "mkdocs"},
expectedTargets: 3,
expectedPackages: []string{"mkdocs", "rich", "pygments"},
},
{
name: "--with shorthand -w",
args: []string{"-w", "rich", "mkdocs"},
expectedTargets: 2,
expectedPackages: []string{"mkdocs", "rich"},
},
{
name: "--from combined with --with",
args: []string{"--from", "mkdocs-material", "--with", "mkdocs", "mkdocs"},
expectedTargets: 2,
expectedPackages: []string{"mkdocs-material", "mkdocs"},
},
{
name: "value flag does not consume the package",
args: []string{"--python", "3.12", "ruff"},
expectedTargets: 1,
expectedPackages: []string{"ruff"},
},
{
name: "boolean flag does not consume the package",
args: []string{"--isolated", "ruff"},
expectedTargets: 1,
expectedPackages: []string{"ruff"},
},
{
name: "reinstall boolean does not consume the package",
args: []string{"--reinstall", "ruff"},
expectedTargets: 1,
expectedPackages: []string{"ruff"},
},
{
name: "no-cache shorthand does not consume the package",
args: []string{"-n", "ruff"},
expectedTargets: 1,
expectedPackages: []string{"ruff"},
},
{
name: "index url value flag",
args: []string{"--index-url", "https://example.com/simple", "ruff"},
expectedTargets: 1,
expectedPackages: []string{"ruff"},
},
{
name: "git+ spec is skipped",
args: []string{"--from", "git+https://github.com/foo/bar@v1", "bar"},
expectedTargets: 0,
},
{
name: "url spec is skipped",
args: []string{"https://example.com/pkg.whl"},
expectedTargets: 0,
},
{
name: "local path spec is skipped",
args: []string{"./local-tool"},
expectedTargets: 0,
},
{
name: "python interpreter request is not audited",
args: []string{"python", "-c", "print(1)"},
expectedTargets: 0,
},
{
name: "versioned python interpreter request is not audited",
args: []string{"python@3.12", "script.py"},
expectedTargets: 0,
},
{
name: "pythonX.Y interpreter request is not audited",
args: []string{"python3.11"},
expectedTargets: 0,
},
{
name: "python interpreter with --with still audits the extra package",
args: []string{"--with", "rich", "python"},
expectedTargets: 1,
expectedPackages: []string{"rich"},
},
{
name: "tool with python-like prefix is still audited",
args: []string{"python-dotenv"},
expectedTargets: 1,
expectedPackages: []string{"python-dotenv"},
},
{
name: "bare uvx invocation",
args: []string{},
expectedTargets: 0,
},
{
name: "uvx prefix is stripped",
args: []string{"uvx", "ruff"},
expectedTargets: 1,
},
}
for _, tc := range cases {
t.Run(tc.name, func(t *testing.T) {
result, err := pm.ParseCommand(tc.args)
require.NoError(t, err)
assert.Equal(t, tc.expectedTargets, len(result.InstallTargets), "number of install targets mismatch")
for i, expectedPkg := range tc.expectedPackages {
if i < len(result.InstallTargets) {
assert.Equal(t, expectedPkg, result.InstallTargets[i].PackageVersion.Package.Name, "package name mismatch for target %d", i)
}
}
})
}
}
// TestUvxExecutorParseCommandVersions pins the resolved name/version and the
// explicit-version flag for pinned specs. These cases use exact versions so no
// registry lookup is needed.
func TestUvxExecutorParseCommandVersions(t *testing.T) {
pm, err := NewPypiPackageExecutor(DefaultUvxPackageExecutorConfig())
require.NoError(t, err)
cases := []struct {
name string
args []string
expectedName string
expectedVersion string
}{
{
name: "positional @ version",
args: []string{"ruff@0.3.0", "check"},
expectedName: "ruff",
expectedVersion: "0.3.0",
},
{
name: "positional == version",
args: []string{"ruff==0.3.0"},
expectedName: "ruff",
expectedVersion: "0.3.0",
},
{
name: "--from with == version",
args: []string{"--from", "httpie==3.2.2", "http"},
expectedName: "httpie",
expectedVersion: "3.2.2",
},
{
name: "--from= with extras and version",
args: []string{"--from=mypy[faster-cache,reports]==1.13.0", "mypy", "--xml-report", "report"},
expectedName: "mypy",
expectedVersion: "1.13.0",
},
}
for _, tc := range cases {
t.Run(tc.name, func(t *testing.T) {
result, err := pm.ParseCommand(tc.args)
require.NoError(t, err)
require.Len(t, result.InstallTargets, 1)
target := result.InstallTargets[0]
assert.Equal(t, tc.expectedName, target.PackageVersion.Package.Name)
assert.Equal(t, tc.expectedVersion, target.PackageVersion.Version)
assert.True(t, target.IsExplicitVersion, "pinned spec should be marked as explicit version")
})
}
}
func TestUvxExecutorProxyBehavior(t *testing.T) {
pm, err := NewPypiPackageExecutor(DefaultUvxPackageExecutorConfig())
require.NoError(t, err)
cases := []struct {
name string
command string
}{
{name: "uvx tool run downloads", command: "uvx ruff"},
{name: "uvx --from run downloads", command: "uvx --from httpie http"},
}
for _, tc := range cases {
t.Run(tc.name, func(t *testing.T) {
parsed, err := pm.ParseCommand(strings.Split(tc.command, " "))
require.NoError(t, err)
// uvx always runs a tool, so it always may download packages and is
// never a known non-download command.
assert.False(t, parsed.IsKnownNonDownloadCommand)
assert.True(t, parsed.MayDownloadPackages())
assert.True(t, parsed.IsInstallationCommand())
})
}
}
func TestUvxNormalizeSpec(t *testing.T) {
cases := []struct {
input string
expected string
}{
{"ruff", "ruff"},
{"ruff@0.3.0", "ruff==0.3.0"},
{"ruff@latest", "ruff"},
{"ruff@", "ruff"},
{"ruff@>=0.3.0", "ruff>=0.3.0"},
{"ruff==0.3.0", "ruff==0.3.0"},
{"mypy[faster-cache]@1.0.0", "mypy[faster-cache]==1.0.0"},
}
for _, tc := range cases {
t.Run(tc.input, func(t *testing.T) {
assert.Equal(t, tc.expected, uvxNormalizeSpec(tc.input))
})
}
}
func TestUvxIsAuditableSpec(t *testing.T) {
cases := []struct {
input string
auditable bool
}{
{"ruff", true},
{"ruff@0.3.0", true},
{"mypy[faster-cache]", true},
{"", false},
{"git+https://github.com/foo/bar", false},
{"https://example.com/pkg.whl", false},
{"file:///tmp/pkg", false},
{"./local", false},
{"../local", false},
{"~/tool", false},
{"/abs/path", false},
{"dist/pkg.tar.gz", false},
{"pkg.whl", false},
}
for _, tc := range cases {
t.Run(tc.input, func(t *testing.T) {
assert.Equal(t, tc.auditable, uvxIsAuditableSpec(tc.input))
})
}
}